Document Analysis
Analyze a document image for scam indicators using vision AI. Upload a photo of a suspicious letter, court notice, receipt, invoice, toll notice, or other document. The pipeline extracts entities (phone numbers, URLs, addresses, officials, legal citations, dollar amounts, dates) using GPT-4o vision, then verifies them in parallel against government databases: - **Addresses:** Smarty US Street API (deliverability, CMRA mailbox detection) + Google Places (institution verification) - **Officials:** CourtListener (federal/state judge database) - **Legal citations:** GovInfo (federal statutes/regulations) + CourtListener (case law) Results are synthesized by AI into a unified risk score with evidence-based verdict. **Supported file types:** JPEG, PNG, WebP, HEIC/HEIF, single-page PDF. **Maximum file size:** 4.5 MB. **Content type:** `multipart/form-data` (not JSON). **Quota:** Consumes 1 document quota per analysis. Document quota is separate from phone/URL/text/email quotas. Cached results (same image hash) do not consume additional quota. **QR codes:** To analyze a QR code, use the dedicated [QR Code Analysis](#tag/QR/POST/qr/analyze) endpoint, which handles server-side decoding and URL verification automatically. **Performance:** Expect 5-15 seconds for a full analysis (vision AI extraction + entity verification + AI synthesis). Cached results return instantly.
Analyze a document image for scam indicators using vision AI. Upload a photo of a suspicious letter, court notice, receipt, invoice, toll notice, or other document.
The pipeline extracts entities (phone numbers, URLs, addresses, officials, legal citations, dollar amounts, dates) using GPT-4o vision, then verifies them in parallel against government databases:
- Addresses: Smarty US Street API (deliverability, CMRA mailbox detection) + Google Places (institution verification)
- Officials: CourtListener (federal/state judge database)
- Legal citations: GovInfo (federal statutes/regulations) + CourtListener (case law)
Results are synthesized by AI into a unified risk score with evidence-based verdict.
Supported file types: JPEG, PNG, WebP, HEIC/HEIF, single-page PDF.
Maximum file size: 4.5 MB.
Content type: multipart/form-data (not JSON).
Quota: Consumes 1 document quota per analysis. Document quota is separate from phone/URL/text/email quotas. Cached results (same image hash) do not consume additional quota.
QR codes: To analyze a QR code, use the dedicated QR Code Analysis endpoint, which handles server-side decoding and URL verification automatically.
Performance: Expect 5-15 seconds for a full analysis (vision AI extraction + entity verification + AI synthesis). Cached results return instantly.
Authorization
BearerAuth API key from your Developer Dashboard.
Keys start with sv_live_ (production) or sv_test_ (test mode).
In: header
Request Body
multipart/form-data
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://scamverify.ai/api/v1/document/analyze" \ -F file="string"{
"id": "doc_42",
"image_hash": "a1b2c3d4e5f6...",
"document_type": "court_document",
"claimed_issuer": "State of Rhode Island Municipal Court",
"risk_score": 92,
"verdict": "dangerous",
"confidence": 0.9,
"explanation": "This document exhibits multiple hallmarks of a fake court notice scam. The address resolves to a commercial mail receiving agency (CMRA), the named judge is not found in any court database, and the cited statute does not exist.",
"scam_pattern": "fake_court_notice",
"red_flags": [
{
"type": "payment_pressure",
"description": "Demands immediate payment via QR code",
"severity": "high",
"evidence": "Scan the QR code below to pay your $450 fine within 48 hours"
},
{
"type": "spelling_error",
"description": "Misspelled court name",
"severity": "medium",
"evidence": "Munisipal Court"
}
],
"extracted_entities": {
"phone_numbers": [
"+18005551234"
],
"urls": [
"https://payment.example.com"
],
"email_addresses": [
"clerk@example.com"
],
"physical_addresses": [
{
"full_address": "123 Main St, Springfield, IL 62701",
"institution_claimed": "Springfield Municipal Court"
}
],
"named_officials": [
{
"name": "John Smith",
"title": "Judge",
"institution": "Springfield Municipal Court"
}
],
"legal_citations": [
"42 U.S.C. section 1983"
],
"dollar_amounts": [
{
"amount": "$450.00",
"context": "fine amount"
}
],
"dates": [
{
"date": "2026-03-15",
"context": "hearing date"
}
]
},
"entity_verifications": {
"addresses": [
{
"address": "123 Main St, Springfield, IL 62701",
"institution_claimed": "Springfield Municipal Court",
"address_valid": true,
"address_deliverable": false,
"is_cmra": true,
"institution_found": false,
"institution_matches": false,
"is_government": false
}
],
"officials": [
{
"name": "John Smith",
"title": "Judge",
"found": false,
"match_confidence": "none"
}
],
"citations": [
{
"citation": "42 U.S.C. section 1983",
"citation_type": "federal_statute",
"verified": true,
"source": "govinfo"
}
]
},
"evidence_summary": [
{
"signal": "Address is a CMRA (mailbox service), not a real court",
"source": "smarty_address_validation",
"impact": "negative"
},
{
"signal": "Named judge not found in any court database",
"source": "courtlistener",
"impact": "negative"
},
{
"signal": "Cited statute exists but is unrelated to court fines",
"source": "govinfo",
"impact": "neutral"
}
],
"recommended_action": "Do not scan the QR code or make any payment. Contact your local court directly using a number from the official government website.",
"sources_checked": [
"vision_extraction",
"address_validation",
"institution_lookup",
"judge_verification",
"citation_verification",
"ai_synthesis"
],
"cached": false,
"cache_expires_at": "2026-03-26T07:00:00.000Z",
"created_at": "2026-03-19T07:00:00.000Z"
}{
"error": {
"code": "validation_error",
"message": "Invalid request body",
"details": {
"issues": [
{
"field": "phone_number",
"message": "phone_number is required"
}
]
}
}
}{
"error": {
"code": "missing_api_key",
"message": "Authorization header is required. Use 'Bearer sv_live_...' format."
}
}{
"error": {
"code": "quota_exhausted",
"message": "Monthly phone quota exhausted. Upgrade your plan for more lookups.",
"upgrade_url": "https://scamverify.ai/settings/api"
}
}{
"error": {
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Please wait before making another request.",
"retry_after": 12
}
}{
"error": {
"code": "internal_error",
"message": "An unexpected error occurred. Please try again later."
}
}Email Analysis POST
Analyze email content and headers for phishing, scam patterns, and sender authenticity. Includes SPF/DKIM/DMARC validation, sender domain analysis, brand impersonation detection, and embedded URL/phone extraction with sub-lookups. **Authentication boosts:** SPF/DKIM failures add +15 to risk score. Return-path mismatch adds +10. Auth failures also trigger verdict floor promotion. **Quota:** Consumes 1 email quota. Sub-lookups do NOT consume additional quota.
QR Code Analysis POST
Upload a QR code image. Server decodes the QR code and analyzes the extracted URL for scam indicators using the full URL verification pipeline. Supported types: JPEG, PNG, WebP. Maximum size: 4.5 MB. If the QR code contains a phone number, email, or non-URL content, the decoded data is returned without URL analysis. **Quota:** Consumes 1 URL quota when a URL is extracted and analyzed. Non-URL QR codes do not consume quota. **Caching:** Results are cached by image hash. Cached lookups do not consume quota and return instantly. **Performance:** Expect 2-8 seconds for a full analysis (QR decode + URL verification pipeline). Cached results return instantly.