API Documentation

Coverage and authentication: Use your Bearer API key for GET or POST; a CSRF token is not required. This endpoint searches imported FCC traceback reports, not live call traces or FTC complaint records. As of September 29, 2026, the dataset contains 3,533 records covering 2024 and no populated phone-number fields. Phone-number searches therefore currently return no matches. This does not mean a number is clean. Use provider/campaign filters and inspect data.coverage. For number reputation, use the spam/trust API. OpenAPI specification.

REST API Endpoints

The Traceback Search API provides RESTful endpoints for searching spam reports, exporting data, and retrieving statistics.

Base URL

https://verirouteintel.com/api/v1/traceback

Available Endpoints

Endpoint Method Description Rate Limit
/search GET/POST Search traceback reports by phone number, provider, or date range Standard
/export GET/POST Export traceback reports in CSV or JSON format Limited
/providers/top-offenders GET Get top offending providers by quarter Standard
/quarters GET List available quarters for traceback data Standard
/stats GET Get aggregated statistics for traceback reports Standard

Search Endpoint

Search through traceback reports using various filters and criteria.

Request

GET/POST /v1/traceback/search

Parameters

Parameter Type Required Description
phone_number string No Phone number to search for (E.164 format recommended)
provider_name string No Filter by provider name
campaign_name string No Filter by campaign name
quarter string No Filter by quarter (e.g., "2024-Q1")
incident_id string No Filter by incident ID
status string No Filter by status
violation_type string No Filter by violation type
provider_role string No Filter by provider role
start_date string No Start date for search (YYYY-MM-DD format)
end_date string No End date for search (YYYY-MM-DD format)
page integer No Page number for pagination (default: 1)
limit integer No Number of results to return (1-100, default: 20)
Date Format: Dates must be in YYYY-MM-DD format (e.g., 2024-01-15). Common mistakes that will cause a 400 error: 01/15/2024, January 15, 2024, 15-01-2024.

Example Request (GET)

curl -X GET "https://verirouteintel.com/api/v1/traceback/search?phone_number=%2B15551234567&start_date=2024-01-01&end_date=2024-01-31&limit=50" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

Example Request (POST with JSON body)

curl -X POST "https://verirouteintel.com/api/v1/traceback/search" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "phone_number": "+15551234567",
       "start_date": "2024-01-01",
       "end_date": "2024-01-31",
       "limit": 50
     }'

Response Format

{
  "success": true,
  "data": {
    "reports": [
      {
        "traceback_id": "TB123456",
        "phone_number": "+15551234567",
        "provider_name": "Example Provider",
        "campaign_name": "Campaign ABC",
        "quarter": "2024-Q1",
        "incident_id": "INC789",
        "status": "ACTIVE",
        "violation_type": "SPAM",
        "provider_role": "ORIGINATING",
        "initiation_date": "2024-01-15"
      }
    ],
    "total_count": 1,
    "page": 1,
    "per_page": 20,
    "total_pages": 1,
    "filters_applied": {
      "phone_number": "+15551234567",
      "start_date": "2024-01-01",
      "end_date": "2024-01-31"
    }
  },
  "credits_used": 0,
  "credits_remaining": 1000
}

Export Endpoint

Export traceback search results in CSV or JSON format.

Request

GET/POST /v1/traceback/export

Parameters

Parameter Type Required Description
format string Yes Export format: "csv" or "json"
All search parameters from /search endpoint are also supported

Example Request

curl -X GET "https://verirouteintel.com/api/v1/traceback/export?format=csv&phone_number=%2B15551234567&start_date=2024-01-01&end_date=2024-01-31" \
     -H "Authorization: Bearer YOUR_API_KEY"

Top Offenders Endpoint

Get top offending providers for a specific quarter.

Request

GET /v1/traceback/providers/top-offenders

Parameters

Parameter Type Required Description
quarter string Yes Quarter to get top offenders for (e.g., "2024-Q1")
limit integer No Number of results to return (1-100, default: 10)

Example Request

curl -X GET "https://verirouteintel.com/api/v1/traceback/providers/top-offenders?quarter=2024-Q1&limit=10" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

Response Format

{
  "success": true,
  "data": {
    "quarter": "2024-Q1",
    "top_offenders": [
      {
        "provider_name": "Example Provider",
        "violation_count": 150,
        "percentage": 25.5
      }
    ]
  }
}

Quarters Endpoint

List available quarters for traceback data.

Request

GET /v1/traceback/quarters

Parameters

This endpoint does not require any parameters.

Example Request

curl -X GET "https://verirouteintel.com/api/v1/traceback/quarters" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

Response Format

{
  "success": true,
  "data": {
    "quarters": [
      "2024-Q1",
      "2023-Q4",
      "2023-Q3"
    ]
  }
}

Stats Endpoint

Get aggregated statistics for traceback reports.

Request

GET /v1/traceback/stats

Parameters

This endpoint does not require any parameters.

Example Request

curl -X GET "https://verirouteintel.com/api/v1/traceback/stats" \
     -H "Authorization: Bearer YOUR_API_KEY" \
     -H "Content-Type: application/json"

Response Format

{
  "success": true,
  "data": {
    "total_reports": 50000,
    "total_providers": 1200,
    "total_campaigns": 8500,
    "latest_quarter": "2024-Q1",
    "role_stats": [
      {
        "provider_role": "ORIGINATING",
        "count": 30000
      },
      {
        "provider_role": "INTERMEDIATE",
        "count": 20000
      }
    ]
  }
}
Need Help? Check out our code examples for implementation guidance, or review our FAQ for common questions.