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",
  "details": "Automated call about car warranty"
}

Successful Response

{
  "success": true,
  "message": "Spam report submitted successfully",
  "data": {
    "phone_number": "+15555550123",
    "report_type": "spam",
    "reported_at": "2025-12-04T15:30:00.000000+00:00",
    "complaint_count": 1
  }
}

Public Spam Reporting (No API Key Required)

This endpoint allows anyone to contribute to our community spam database without requiring an API key. Perfect for landing pages, public forms, and mobile apps where exposing API keys is not desirable.

Request Body

{
  "phone_number": "15555550123",
  "report_type": "robocall",
  "details": "Automated call claiming to be IRS",
  "source": "my-website"
}

Parameters

Successful Response

{
  "success": true,
  "message": "Thank you! Your spam report has been submitted.",
  "data": {
    "phone_number": "+15555550123",
    "report_type": "robocall",
    "total_reports": 5
  }
}

Error Response (Duplicate Report)

{
  "error": "You have already reported this number recently. Please wait before reporting again.",
  "code": "DUPLICATE_REPORT"
}

Batch Spam Lookup

Look up spam reputation for up to 100 phone numbers in a single request with automatic deduplication and two-phase billing.

Request Body

{
  "phone_numbers": ["15555550123", "19494600638", "15555550123"],
  "check_spam": true
}

Response

{
  "job_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "results": [
    {
      "phone_number": "15555550123",
      "is_spam": true,
      "is_robocall": false,
      "is_scam": false,
      "spam_type": "SPAM",
      "source": "MCL_PROVIDER",
      "cached": false,
      "input_indices": [0, 2],
      "status": "success"
    },
    {
      "phone_number": "19494600638",
      "is_spam": false,
      "is_robocall": false,
      "is_scam": false,
      "source": "MCL_PROVIDER",
      "cached": false,
      "input_indices": [1],
      "status": "success"
    }
  ],
  "summary": {
    "submitted": 3,
    "unique": 2,
    "duplicates_removed": 1,
    "succeeded": 2,
    "failed": 0,
    "from_cache": 0,
    "invalid_count": 0,
    "breakdown": {
      "success": 2,
      "failed": 0,
      "invalid_format": 0
    }
  },
  "billing": {
    "estimated_cost": 0.02,
    "actual_cost": 0.02,
    "savings_from_deduplication": 0.01,
    "per_lookup_rate": 0.01
  },
  "timing": {
    "submitted_at": "2025-12-20T10:30:00Z",
    "started_at": "2025-12-20T10:30:00Z",
    "completed_at": "2025-12-20T10:30:01Z",
    "duration_ms": 1234
  }
}

Key Features

• Automatic Deduplication: Duplicate phone numbers are detected and only charged once. The input_indices field shows which positions in your input array map to each result.
• Two-Phase Billing: Balance is reserved before processing and settled after completion. Failed lookups are not charged.
• Full Transparency: Response includes detailed summary, billing breakdown, and timing information.
• Job Tracking: Each batch request gets a unique job_id for audit and support purposes.

Parameters

Code Examples

Authenticated Spam Reporting

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",
    "details": "Automated warranty call"
}

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',
      details: 'Automated warranty call'
    })
  });

  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",
    "details": "Automated warranty call"
  }'

Public Spam Reporting (No API Key)

Use these examples to report spam from public-facing applications without exposing your API key.

// No API key needed - perfect for landing pages!
async function reportSpamNumber(phoneNumber, reportType, details) {
  const response = await fetch('https://api-service.verirouteintel.io/api/v1/spam/report/public', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      phone_number: phoneNumber,
      report_type: reportType,  // spam, robocall, scam, etc.
      details: details,
      source: 'my-website'  // Identify your app
    })
  });

  const result = await response.json();
  if (result.success) {
    alert('Thank you! Your report has been submitted.');
  } else {
    alert('Error: ' + result.error);
  }
}

import requests

# Public endpoint - no API key required
url = "https://api-service.verirouteintel.io/api/v1/spam/report/public"
headers = {"Content-Type": "application/json"}

data = {
    "phone_number": "15555550123",
    "report_type": "robocall",
    "details": "Automated IRS scam call",
    "source": "my-app"  # Track where reports come from
}

response = requests.post(url, headers=headers, json=data)
print(response.json())
# {"success": true, "message": "Thank you! Your spam report has been submitted.", ...}

# No Authorization header needed!
curl -X POST https://api-service.verirouteintel.io/api/v1/spam/report/public \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "15555550123",
    "report_type": "scam",
    "details": "Caller claimed to be from the IRS",
    "source": "my-landing-page"
  }'

<form id="spam-report-form">
  <input type="tel" id="phone" placeholder="Phone number" required>
  <select id="report-type">
    <option value="spam">Spam</option>
    <option value="robocall">Robocall</option>
    <option value="scam">Scam</option>
    <option value="telemarketing">Telemarketing</option>
  </select>
  <textarea id="details" placeholder="Describe the call..."></textarea>
  <button type="submit">Report Spam</button>
</form>

<script>
document.getElementById('spam-report-form').addEventListener('submit', async (e) => {
  e.preventDefault();

  const response = await fetch('https://api-service.verirouteintel.io/api/v1/spam/report/public', {
    method: 'POST',
    headers: {'Content-Type': 'application/json'},
    body: JSON.stringify({
      phone_number: document.getElementById('phone').value,
      report_type: document.getElementById('report-type').value,
      details: document.getElementById('details').value,
      source: 'my-website'
    })
  });

  const result = await response.json();
  alert(result.success ? 'Report submitted!' : result.error);
});
</script>

Error Handling

Common Error Responses

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

{
  "error": "Invalid report_type. Must be one of: spam, robocall, scam, telemarketing, fraud, phishing",
  "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
}

{
  "error": "Duplicate report detected. You have already reported this number within the last 24 hours.",
  "code": "DUPLICATE_REPORT",
  "data": {
    "phone_number": "+15555550123",
    "last_reported": "2025-12-04T10:30:00.000000+00:00",
    "retry_after": "2025-12-05T10:30:00.000000+00:00"
  }
}

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 per minute 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: 60

429 Too Many Requests

When rate limits are exceeded, the API returns a 429 status code:

{
  "error": "Rate limit exceeded",
  "message": "Too many requests. Please wait before making another request.",
  "retry_after": 60
}