API Documentation

REST API Endpoints

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

Base URL

https://api.numberintelligence.com/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)

Example Request

curl -X GET "https://api.numberintelligence.com/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"

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://api.numberintelligence.com/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://api.numberintelligence.com/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://api.numberintelligence.com/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://api.numberintelligence.com/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.