API Reference

Complete reference for all ScamVerify™ API endpoints with interactive playground.

The ScamVerify™ API provides 8 endpoints across 4 verification channels, plus batch processing and account management.

Every endpoint below includes request/response schemas, code examples in multiple languages, and an interactive playground where you can test with your API key.

Authentication

All endpoints except /status require a Bearer token:

Authorization: Bearer sv_live_your_api_key_here

Verification Endpoints

Phone Lookup

POST /api/v1/phone/lookup. Risk assessment using FTC/FCC complaints, carrier data, robocall detection, and AI synthesis.

URL Lookup

POST /api/v1/url/lookup. Domain analysis with URLhaus, ThreatFox, SSL inspection, brand impersonation detection, and WHOIS data.

Text Analysis

POST /api/v1/text/analyze. SMS scam detection with embedded URL/phone extraction, sub-lookups, and unified scoring.

Email Analysis

POST /api/v1/email/analyze. Phishing detection with SPF/DKIM/DMARC validation, sender forensics, and header analysis.

Batch Endpoints

Batch Phone

POST /api/v1/batch/phone. Process up to 100 phone numbers in a single request.

Batch URL

POST /api/v1/batch/url. Process up to 100 URLs in a single request.

Account Endpoints

Usage & Quota

GET /api/v1/usage. Check your current plan, per-channel quota usage, and rate limit configuration.

System Status

GET /api/v1/status. Health check for all API components. No authentication required.

Response Format

All endpoints return JSON. Successful lookups include:

Field	Description
`risk_score`	0-100 integer (0 = safe, 100 = confirmed scam)
`verdict`	`safe`, `low_risk`, `medium_risk`, `high_risk`, or `scam`
`confidence`	0.0 to 1.0 confidence level
`explanation`	AI-generated plain-English risk assessment
`signals`	Detailed per-source signal breakdown
`cached`	Whether the result was served from cache

Error Format

All errors follow a consistent structure:

{
  "error": {
    "code": "validation_error",
    "message": "Invalid request body",
    "details": { "issues": [{ "field": "phone_number", "message": "Required" }] }
  }
}

See the Error Handling guide for all error codes and retry strategies.