Channels

ScamVerify™ provides six verification channels. Each is designed for a specific type of threat and returns a tailored set of signals. All six channels share the same risk score scale (0 to 100) and verdict system.

Phone

The phone channel verifies U.S. phone numbers against FTC/FCC complaint databases, carrier infrastructure data, robocall detection systems, and community reports.

Request

{
  "phone_number": "+12125551234"
}

Signals Object

The signals object in a phone response contains:

{
  "signals": {
    "ftc_complaints": 47,
    "ftc_most_recent": "2026-01-15",
    "ftc_categories": ["Robocalls", "Reducing your debt"],
    "fcc_complaints": 3,
    "carrier": "Bandwidth.com",
    "line_type": "nonFixedVoip",
    "caller_name": null,
    "robocall_flagged": true,
    "high_risk_carrier": true,
    "line_status": "active",
    "community_reports": 12,
    "community_scam_rate": 0.83
  }
}

When to Use

Use the phone channel when you need to evaluate the risk of an incoming call, verify a phone number provided by a user, or screen phone numbers in a contact database. Common use cases include caller ID apps, CRM enrichment, and fraud screening for financial transactions.

URL

The URL channel verifies websites and domains against threat intelligence feeds, domain registration data, SSL certificates, and brand impersonation detection.

Request

{
  "url": "https://secure-login.example.com/verify"
}

Signals Object

The signals object in a URL response contains:

{
  "signals": {
    "domain_age_days": 12,
    "registrar": "Namecheap, Inc.",
    "ssl_issuer": "Let's Encrypt",
    "ssl_age_days": 10,
    "redirect_count": 3,
    "brand_impersonation": {
      "detected": true,
      "brand": "Chase Bank",
      "confidence": 0.92
    },
    "google_web_risk": "SOCIAL_ENGINEERING",
    "urlhaus_listed": false,
    "threatfox_listed": true,
    "ipqs_risk_score": 88,
    "community_reports": 0
  }
}

When to Use

Use the URL channel when you need to verify a link before a user clicks it, scan URLs in user-generated content, or evaluate domains during web scraping. Common use cases include link scanners, content moderation, browser extensions, and phishing detection in chat platforms.

Text

The text channel analyzes SMS and text messages for scam indicators. It combines AI-powered language analysis with automated sub-lookups of embedded URLs and phone numbers.

How Extraction Works

When you submit a text message, the pipeline:

1. Extracts URLs from the message body (up to 3 URLs)
2. Extracts phone numbers from the message body (up to 3 phone numbers)
3. Runs sub-lookups on each extracted URL and phone number through the URL and phone pipelines
4. Sends everything to AI analysis, which sees both the message text and the sub-lookup results
5. Computes a unified risk score by combining the AI analysis (60% weight) with sub-lookup results (40% weight)

If you provide a from_number parameter, that sender's phone number is also verified through the phone pipeline and included in the sub-lookup results.

Request

{
  "message": "URGENT: Your bank account has been compromised. Visit secure-verify.example.com or call 1-800-555-0199 to restore access immediately.",
  "from_number": "+12125559876"
}

Response Structure

{
  "id": "txt_4821",
  "message_hash": "a1b2c3d4e5f6...",
  "risk_score": 78,
  "verdict": "high_risk",
  "confidence": 0.84,
  "explanation": "This message exhibits multiple scam indicators...",
  "red_flags": [
    "Creates urgency with 'URGENT' and 'immediately'",
    "Claims account compromise to provoke fear",
    "Contains a suspicious URL on a 12-day-old domain",
    "Includes a phone number for social engineering"
  ],
  "scam_type": "bank_impersonation",
  "extracted": {
    "phone_numbers": ["+18005550199"],
    "urls": ["https://secure-verify.example.com"]
  },
  "sub_lookups": {
    "phones": [{ "...phone result..." }],
    "urls": [{ "...url result..." }]
  },
  "unified_risk_score": 78,
  "sources_checked": ["language_analysis", "phone_lookup", "url_lookup", "ai_analysis"]
}

The sub_lookups object contains full phone and URL results for each extracted entity, using the same response format as standalone phone and URL lookups.

When to Use

Use the text channel when you need to evaluate SMS messages, chat messages, or any short-form text for scam indicators. Common use cases include SMS filtering apps, chat platform moderation, and customer support ticket screening.

Email

The email channel analyzes full email messages. It includes everything the text channel does, plus email-specific analysis of sender reputation and authentication headers.

Additional Capabilities

Beyond the text channel's extraction and sub-lookup system, email adds:

Header authentication analysis - When you provide raw_headers, the pipeline parses SPF, DKIM, and DMARC results. Authentication failures directly boost the risk score (+15 for SPF/DKIM failures, +10 for return-path mismatch).

Sender domain analysis - The sender's email domain is evaluated for age, registrar, and brand impersonation. A 3-day-old domain sending emails that claim to be from a major bank is a strong scam signal.

Request

{
  "email_body": "Dear Customer, We detected unusual activity on your account...",
  "sender_email": "support@secure-banking-alerts.com",
  "subject": "Urgent: Account Security Alert",
  "raw_headers": "Received: from mail.example.com...\nAuthentication-Results: spf=fail..."
}

Response Structure

The email response includes two additional objects not present in text responses:

{
  "sender_analysis": {
    "domain": "secure-banking-alerts.com",
    "domain_age_days": 5,
    "brand_impersonation": {
      "detected": true,
      "brand": "Wells Fargo"
    }
  },
  "header_analysis": {
    "spf": "fail",
    "dkim": "fail",
    "dmarc": "fail",
    "return_path_mismatch": true
  }
}

If raw_headers is not provided, header_analysis will be null. The AI analysis and scoring still work without headers, but authentication signals will not contribute to the score.

When to Use

Use the email channel when you need to evaluate full email messages, especially when you have access to email headers. Common use cases include email security gateways, phishing detection for enterprise mailboxes, and customer-facing "is this email a scam?" tools.

Document

The document channel analyzes uploaded documents (letters, invoices, court notices, government correspondence) for scam indicators. It uses GPT-4o Vision AI to extract entities from document images, then cross-references claimed institutions, officials, addresses, legal citations, and contact information against authoritative databases.

Request

Document uploads use multipart/form-data instead of JSON:

curl -X POST https://api.scamverify.ai/v1/verify/document \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -F "file=@suspicious-letter.pdf" \
  -F "description=Received this letter claiming to be from the IRS"

The file field accepts PDF, PNG, JPG, and JPEG formats. The optional description field provides additional context for the AI analysis.

Response Highlights

{
  "document_type": "government_notice",
  "claimed_issuer": "Internal Revenue Service",
  "extracted_entities": {
    "phone_numbers": ["+18005551234"],
    "urls": ["https://irs-payment-portal.example.com"],
    "addresses": ["1234 Federal Plaza, Suite 100, Washington DC 20001"],
    "officials": ["Agent Robert Williams, Badge #4521"],
    "citations": ["26 USC 6331", "IRC Section 7602"],
    "dollar_amounts": ["$4,827.00"],
    "dates": ["2026-04-15"]
  },
  "entity_verifications": {
    "address_validation": { "valid": false, "is_cmra": true },
    "institution_verification": { "found": false, "matches_claimed": false },
    "official_verification": { "found": false, "match_confidence": "none" },
    "citation_verification": { "verified": true, "citation_type": "uscode" }
  },
  "red_flags": [
    "Address is a Commercial Mail Receiving Agency (CMRA), not a government office",
    "No matching IRS office found at the claimed address",
    "Named official not found in federal databases",
    "URL domain is 5 days old, not an official .gov domain"
  ],
  "scam_pattern": "government_impersonation",
  "risk_score": 91,
  "verdict": "scam"
}

Verification Sources

When to Use

Use the document channel when you need to evaluate suspicious physical mail or digital documents. Common use cases include court notices, arrest warrants, IRS notices, toll violation letters, utility shutoff threats, invoices from unknown companies, and any letter demanding immediate payment or legal action.

QR Code

The QR code channel decodes QR codes locally and routes the extracted URL through the URL verification pipeline. This provides the same depth of URL analysis (threat intelligence, domain registration, brand impersonation, community reports) without requiring the user to manually extract and submit the URL.

Two-Step Flow

QR code verification is a two-step process:

1. Decode the QR code image to extract the embedded URL
2. Submit the extracted URL to the URL verification endpoint

import requests

# Step 1: Decode the QR code (client-side or via a library)
from pyzbar.pyzbar import decode
from PIL import Image

qr_image = Image.open("suspicious-qr.png")
decoded = decode(qr_image)
extracted_url = decoded[0].data.decode("utf-8")

# Step 2: Submit the URL to ScamVerify™
response = requests.post(
    "https://api.scamverify.ai/v1/verify/url",
    headers={"Authorization": "Bearer YOUR_API_KEY"},
    json={"url": extracted_url}
)

result = response.json()
print(f"Verdict: {result['verdict']} (score: {result['risk_score']})")

The response is identical to a standard URL lookup. See the URL channel section above for the full response format.

When to Use

Use the QR code channel when you encounter QR codes in unexpected or suspicious contexts. Common use cases include parking meter QR codes, QR codes on unexpected packages, QR codes in suspicious emails or text messages, restaurant menu QR codes that seem unusual, and QR codes posted in public spaces.

Note: QR code lookups consume URL quota, not document quota. Each decoded QR code counts as one URL lookup.

Cross-Channel Intelligence

The text and email channels leverage the phone and URL pipelines internally. When a text message contains a phone number and a URL, the ScamVerify™ pipeline runs three lookups in one request:

1. A phone lookup on the extracted number
2. A URL lookup on the extracted link
3. An AI analysis of the full message, informed by the sub-lookup results

This cross-channel approach catches threats that single-channel analysis would miss. A message might use innocent language, but if it links to a domain listed in ThreatFox, the unified score reflects that threat.

The sub-lookup results are included in the response under sub_lookups, giving you full visibility into each extracted entity's risk assessment.

Quota Allocation

Text and email lookups consume more resources than phone and URL lookups because they trigger multiple sub-lookups internally. To reflect this, text and email channels receive half the monthly quota of phone and URL channels. Document lookups have their own separate quota:

A single text or email lookup may trigger up to 6 sub-lookups (3 URLs + 3 phone numbers), but it only counts as 1 text or email lookup against your quota. Sub-lookups are not counted separately. QR code lookups consume URL quota, not document quota.

You can check your current quota usage at any time via the GET /v1/usage endpoint.