Spam Reporting API – Report Phone Number Spam

Community-Driven Spam Protection

The Spam Reporting API allows you to report spam, robocalls, and scam phone numbers to our master spam database. Your reports help protect the entire community by building a comprehensive database of malicious phone numbers.

Authentication

All API requests require authentication using your API key. Include your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

Don't have an API key? Get your API key here.

API Methods

Report Spam Number

Request Body

{
  "phone_number": "15555550123",
  "report_type": "spam",
  "caller_name": "Fake Insurance Company",
  "description": "Automated call about car warranty",
  "incident_date": "2024-01-15T14:30:00Z"
}

Successful Response

{
  "success": true,
  "message": "Spam report submitted successfully",
  "data": {
    "phone_number": "15555550123",
    "report_id": "rpt_abc123def456",
    "status": "processed",
    "contribution_points": 10
  }
}

Parameters

Code Examples

import requests
import json
from datetime import datetime

url = "https://api-service.verirouteintel.io/api/v1/spam/report"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
    "Content-Type": "application/json"
}

data = {
    "phone_number": "15555550123",
    "report_type": "spam",
    "caller_name": "Fake Insurance",
    "description": "Automated warranty call",
    "incident_date": datetime.now().isoformat() + "Z"
}

response = requests.post(url, headers=headers, json=data)
print(response.json())

const reportSpam = async () => {
  const response = await fetch('https://api-service.verirouteintel.io/api/v1/spam/report', {
    method: 'POST',
    headers: {
      'Authorization': 'Bearer YOUR_API_KEY',
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: '15555550123',
      report_type: 'spam',
      caller_name: 'Fake Insurance',
      description: 'Automated warranty call',
      incident_date: new Date().toISOString()
    })
  });
  
  const result = await response.json();
  console.log(result);
};

curl -X POST https://api-service.verirouteintel.io/api/v1/spam/report \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "15555550123",
    "report_type": "spam",
    "caller_name": "Fake Insurance",
    "description": "Automated warranty call",
    "incident_date": "2024-01-15T14:30:00Z"
  }'

Error Handling

Common Error Responses

{
  "success": false,
  "error": "Invalid phone number format",
  "code": "INVALID_PHONE_NUMBER"
}

{
  "success": false,
  "error": "Invalid report type. Must be one of: spam, robocall, scam, telemarketing, political",
  "code": "INVALID_REPORT_TYPE"
}

{
  "success": false,
  "error": "Rate limit exceeded. Maximum 50 reports per hour, 5 per minute.",
  "code": "RATE_LIMIT_EXCEEDED",
  "retry_after": 3600
}

{
  "success": false,
  "error": "Duplicate report. You have already reported this number within the last 24 hours.",
  "code": "DUPLICATE_REPORT"
}

Rate Limits

To prevent abuse and ensure fair usage, the Spam Reporting API has the following rate limits:

• 50 reports per hour per API key
• 5 reports per minute per API key
• 1 report per phone number per 24 hours per API key (duplicate prevention)

Rate limit headers are included in all responses:

X-RateLimit-Limit: 50
X-RateLimit-Remaining: 49
X-RateLimit-Reset: 1642262400