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 Search spam reports by phone number, date range, or content Standard
/export GET Export spam reports in CSV or JSON format Limited
/stats GET Get aggregated statistics for spam reports Standard

Search Endpoint

Search through spam reports using various filters and criteria.

Request

GET /v1/traceback/search

Parameters

Parameter Type Required Description
sender_number string No Phone number to search for (E.164 format recommended)
start_date string No Start date for search (ISO 8601 format)
end_date string No End date for search (ISO 8601 format)
message_content string No Search within message content (case-insensitive)
spam_type string No Filter by spam type: phishing, scam, marketing, etc.
carrier string No Filter by originating carrier
limit integer No Number of results to return (1-1000, default: 100)
offset integer No Number of results to skip (default: 0)

Example Request

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

Response Format

{
  "success": true,
  "data": {
    "reports": [
      {
        "id": "rpt_abc123",
        "sender_number": "+15551234567",
        "message_content": "Congratulations! You've won...",
        "spam_type": "scam",
        "reported_at": "2024-01-15T14:30:00Z",
        "carrier_info": {
          "name": "Example Carrier",
          "country": "US"
        },
        "confidence_score": 0.95
      }
    ],
    "pagination": {
      "total_count": 1250,
      "limit": 50,
      "offset": 0,
      "has_more": true
    }
  },
  "request_id": "req_xyz789"
}

Export Endpoint

Export spam reports in bulk for analysis and reporting purposes.

Request

GET /v1/traceback/export

Parameters

Parameter Type Required Description
format string Yes Export format: csv or json
sender_number string No Phone number to export reports for
start_date string No Start date for export (ISO 8601 format)
end_date string No End date for export (ISO 8601 format)
include_content boolean No Include message content in export (default: false)

Example Request

curl -X GET "https://api.numberintelligence.com/v1/traceback/export?format=csv&sender_number=%2B15551234567&start_date=2024-01-01T00:00:00Z" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --output spam_report.csv

Statistics Endpoint

Get aggregated statistics and insights from spam report data.

Request

GET /v1/traceback/stats

Parameters

Parameter Type Required Description
metric string Yes Statistic type: top_senders, spam_types, carriers, daily_counts
start_date string No Start date for statistics (ISO 8601 format)
end_date string No End date for statistics (ISO 8601 format)
limit integer No Number of results to return (1-100, default: 10)

Example Request

curl -X GET "https://api.numberintelligence.com/v1/traceback/stats?metric=top_senders&limit=10" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json"

Response Format

{
  "success": true,
  "data": {
    "metric": "top_senders",
    "period": {
      "start_date": "2024-01-01T00:00:00Z",
      "end_date": "2024-01-31T23:59:59Z"
    },
    "results": [
      {
        "sender_number": "+15551234567",
        "report_count": 1250,
        "spam_types": ["scam", "phishing"],
        "first_seen": "2024-01-01T08:15:00Z",
        "last_seen": "2024-01-31T19:45:00Z"
      }
    ]
  },
  "request_id": "req_stats123"
}

Advanced Search Filters

Use advanced filtering options to refine your spam report searches.

Spam Type Filtering

Filter reports by specific spam categories:

  • phishing - Identity theft and credential harvesting
  • scam - Financial scams and fraud attempts
  • marketing - Unwanted promotional messages
  • malware - Messages containing malicious links
  • other - Miscellaneous spam types

Date Range Filtering

Search within specific time periods using ISO 8601 format:

# Last 30 days
start_date=2024-01-01T00:00:00Z&end_date=2024-01-31T23:59:59Z

# Specific day
start_date=2024-01-15T00:00:00Z&end_date=2024-01-15T23:59:59Z

Carrier Filtering

Filter by originating carrier to identify patterns:

  • Major US carriers: Verizon, AT&T, T-Mobile, Sprint
  • VoIP providers: Twilio, Bandwidth, Telnyx
  • International carriers by country code
Need Help? Check out our code examples for implementation guidance, or review our FAQ for common questions.