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 authenticated endpoints require your API key in the request headers:

Authorization: Bearer YOUR_API_KEY

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

Spam Lookup

Check if phone numbers are reported as spam, robocalls, or scams using our multi-source spam detection.

Basic Spam Lookup

Quick spam check for a single phone number. Available via GET or POST.

Request Parameters

POST Request Body

{
  "phone_number": "15555550123",
  "check_spam": true
}

Response

{
  "phone_number": "15555550123",
  "is_spam": true,
  "is_robocall": false,
  "is_scam": false,
  "spam_type": "SPAM",
  "cached": false,
  "source": "enhanced"
}

Response Fields

Enhanced Multi-Source Spam Lookup

Advanced spam detection that aggregates data from multiple sources for comprehensive spam intelligence with confidence scores.

Request Body

{
  "phone_number": "15555550123",
  "include_web_sources": true,
  "include_provider": true
}

Parameters

Response

{
  "phone_number": "15555550123",
  "is_spam": true,
  "is_robocall": true,
  "is_scam": false,
  "spam_type": "ROBOCALL",
  "confidence": 0.92,
  "total_complaints": 15,
  "sources": ["database", "provider", "web"],
  "categories": ["Warranties", "Auto"]
}

Enhanced Response Fields

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
  },
  "billing": {
    "estimated_cost": 0.02,
    "actual_cost": 0.02,
    "savings_from_deduplication": 0.01
  },
  "timing": {
    "submitted_at": "2026-01-18T10:30:00Z",
    "completed_at": "2026-01-18T10: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.

Spam Reporting

Report spam, robocalls, and scam phone numbers to our master spam database. Your reports help protect the entire community.

Report Spam Number (Authenticated)

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"
}

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"
  }'

// 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>

{
  "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"
  }
}

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

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