API Reference
Complete reference for all ScamVerify™ API endpoints with interactive playground.
The ScamVerify™ API provides 10 endpoints across 6 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_hereVerification 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.
Document Analysis
POST /api/v1/document/analyze. Vision AI document scanning with entity extraction and government database verification. Supports court notices, invoices, toll notices, and more.
QR Code Analysis
POST /api/v1/qr/analyze. Upload a QR code image for server-side decoding and URL verification. Detects phishing QR codes on parking meters, restaurant menus, and packages.
QR Codes
There are two ways to analyze a QR code:
Option 1: Upload the image directly (recommended). Send the QR code image to the dedicated QR endpoint. The server handles decoding and runs the full URL verification pipeline automatically.
curl -X POST https://scamverify.ai/api/v1/qr/analyze \
-H "Authorization: Bearer sv_live_your_key" \
-F "file=@qr-code.png"Option 2: Decode locally and use URL Lookup. If you already have the decoded URL (e.g., from a camera SDK), you can skip the QR endpoint and send the URL directly.
# Python example: decode QR code locally and check the URL
import cv2
from pyzbar.pyzbar import decode
import requests
# Decode QR code from image
image = cv2.imread("qr-code.png")
decoded = decode(image)
url = decoded[0].data.decode("utf-8")
# Send to URL Lookup endpoint
response = requests.post(
"https://scamverify.ai/api/v1/url/lookup",
headers={"Authorization": "Bearer sv_live_your_key"},
json={"url": url}
)
print(response.json()["verdict"]) # "dangerous", "high_risk", etc.// Node.js example: decode QR code locally and check the URL
import jsQR from 'jsqr';
import sharp from 'sharp';
// Decode QR code from image file
const { data, info } = await sharp('qr-code.png')
.ensureAlpha()
.raw()
.toBuffer({ resolveWithObject: true });
const qr = jsQR(new Uint8ClampedArray(data), info.width, info.height);
const url = qr?.data;
// Send to URL Lookup endpoint
const res = await fetch('https://scamverify.ai/api/v1/url/lookup', {
method: 'POST',
headers: {
'Authorization': 'Bearer sv_live_your_key',
'Content-Type': 'application/json',
},
body: JSON.stringify({ url }),
});
const result = await res.json();
console.log(result.verdict); // "dangerous", "high_risk", etc.Both options consume 1 URL quota when a URL is analyzed. Non-URL QR codes (phone numbers, email addresses, vCards) are decoded and returned without consuming quota.
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.
SDKs and Libraries
Use the ScamVerify™ API from Python, Node.js, Go, PHP, Ruby, and other languages using standard HTTP clients.
Phone Number Lookup POST
Look up a U.S. phone number against FTC/FCC complaint databases, carrier records, robocall detection, community reports, and AI synthesis. Returns a risk score (0-100), verdict, confidence level, detailed signals, and an AI-generated plain-English explanation. **Data sources checked:** FTC Do Not Call (3M+ records, synced hourly), FCC Consumer Complaints, Twilio (carrier, CNAM, line type), Robocall Detection Database, IPQS phone reputation, community reports, 18 flagged high-risk VoIP carriers. **Caching:** Results are cached for 24 hours. Use `force_refresh: true` to bypass cache (still counts toward quota). Cached lookups do not consume quota.