One Endpoint, Every Content Type

OrbGuard's scam detection is built around a single, unified analysis endpoint. Rather than juggling a different route for each media type, you call POST /api/v1/scam/analyze and set the content_type field to tell the engine what it is looking at -- text, URL, image, voice, or phone. The same multi-modal AI engine then combines large-language-model reasoning with pattern matching to detect social engineering, impersonation, deepfake audio, investment fraud, romance scams, and phishing.

POST/api/v1/scam/analyze

Analyze content of any supported type for scam patterns using AI

Authentication:Bearer Token

Parameter	Type	Required	Description
`content`	string	Required	The content to analyze. For text/url/phone this is the raw text, URL, or phone number. For image and voice this is the media file Base64-encoded.
`content_type`	string	Optional	What the content is. One of: text, url, image, voice, phone. Defaults to text if omitted.
`url`	string	Optional	The URL under analysis. Set this in addition to content when content_type is url so the engine can extract domain and path features.
`phone_number`	string	Optional	The phone number under analysis, in international format (e.g. +1-555-0199). Used with content_type phone.
`sender`	string	Optional	The sender's phone number or identifier, when known (e.g. the SMS originator). Improves sender-reputation scoring.
`mime_type`	string	Optional	MIME type of the Base64 payload for image or voice analysis (e.g. image/png, audio/wav).
`language`	string	Optional	ISO 639-1 language code for the content (e.g. en, fa, ar, ru). Auto-detected if not provided.
`device_id`	string	Optional	Optional device identifier used to correlate reports and tune on-device protection.

How Image and Voice Work

For image and voice, put the Base64-encoded media in the content field and set mime_type accordingly. The engine decodes it server-side. Vision and speech analyzers are capability-gated: if a media analyzer is not enabled for your deployment, the endpoint returns 503 with {"code":"analyzer_not_enabled"} rather than a misleading "safe" verdict.

Analyze a Text Message

curl -X POST https://guard.orbai.world/api/v1/scam/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "text",
    "content": "Congratulations! You have won $1,000,000 in the International Lottery. Send your bank details to claim your prize immediately. This offer expires in 24 hours!",
    "language": "en",
    "sender": "+1-202-555-0143"
  }'

200Scam analysis complete

{
  "is_scam": true,
  "scam_type": "lottery",
  "severity": "high",
  "risk_score": 0.94,
  "explanation": "This message exhibits classic advance-fee lottery fraud characteristics. It claims the recipient won a lottery they never entered, requests sensitive bank details, and creates artificial urgency to prevent the victim from thinking critically.",
  "indicators": [
    "Unsolicited lottery/prize notification",
    "Request for financial information",
    "Artificial urgency and time pressure",
    "Unrealistic monetary reward"
  ],
  "recommendation": "Do not respond. Delete this message. Never share bank details or send money to claim a prize.",
  "analysis_method": "hybrid"
}

Analyze a URL

Set content_type to url and provide the link in both content and url.

curl -X POST https://guard.orbai.world/api/v1/scam/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "url",
    "content": "https://secure-banking-login.example.com/verify-account",
    "url": "https://secure-banking-login.example.com/verify-account"
  }'

Analyze an Image (Base64)

For screenshots of messages, fake documents, or QR-code scams, Base64-encode the image into content and set mime_type.

IMAGE_DATA=$(base64 -i /path/to/screenshot.png)
curl -X POST https://guard.orbai.world/api/v1/scam/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"content_type\": \"image\",
    \"content\": \"$IMAGE_DATA\",
    \"mime_type\": \"image/png\"
  }"

Analyze a Voice Recording (Base64)

Detects deepfake audio, vishing, and phone-based social engineering. Base64-encode the audio into content and set mime_type.

AUDIO_DATA=$(base64 -i /path/to/call-recording.wav)
curl -X POST https://guard.orbai.world/api/v1/scam/analyze \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{
    \"content_type\": \"voice\",
    \"content\": \"$AUDIO_DATA\",
    \"mime_type\": \"audio/wav\"
  }"

503Media analyzer not enabled for this deployment

{
  "error": "vision analyzer not enabled",
  "code": "analyzer_not_enabled"
}

400Invalid request

{
  "error": "content is required"
}

Scam Types

The engine classifies scams into the following categories:

Scam Type	Description
`phishing`	Credential theft via fake login pages or deceptive messages
`romance`	Emotional manipulation for financial exploitation
`investment`	Fraudulent investment schemes and Ponzi promises
`tech_support`	Fake technical support to gain access or charge fees
`lottery`	Fake lottery or prize-winning notifications (advance-fee fraud)
`impersonation`	Impersonating a known person, company, or authority
`shipping`	Fake delivery notifications with malicious links
`banking`	Fake banking alerts designed to steal credentials

Analysis Methods

The analysis_method field reports how the verdict was reached:

Method	Description
`llm`	AI language-model analysis for nuanced understanding
`pattern`	Pattern matching against known scam templates
`hybrid`	Combined LLM and pattern matching for highest accuracy

Scam Pattern Library

Retrieve the current catalog of scam types and risk indicators the engine recognizes. Useful for building client-side hints, educational content, or local pre-filters.

GET/api/v1/scam/patterns

List the scam types and risk indicators recognized by the engine

Authentication:Bearer Token

curl -X GET https://guard.orbai.world/api/v1/scam/patterns \
  -H "Authorization: Bearer YOUR_TOKEN"

200Scam pattern library

{
  "version": "1.0.0",
  "last_updated": "2026-02-08T10:00:00Z",
  "scam_types": [
    {
      "type": "phishing",
      "description": "Attempts to steal personal information through fake communications",
      "indicators": ["urgency", "fake links", "personal info requests"]
    },
    {
      "type": "romance",
      "description": "Emotional manipulation for financial gain",
      "indicators": ["quick emotional connection", "financial requests", "avoids meeting"]
    },
    {
      "type": "investment",
      "description": "Fake investment opportunities promising high returns",
      "indicators": ["guaranteed returns", "urgency to invest", "unregistered platform"]
    }
  ],
  "risk_indicators": [
    "urgency_pressure", "financial_request", "personal_info_request",
    "suspicious_links", "grammar_errors", "too_good_to_be_true",
    "emotional_manipulation", "authority_impersonation",
    "unsolicited_contact", "payment_unusual_method"
  ]
}

Phone Number Reputation

Check a phone number's reputation by running it through the scam engine. Returns a 0-100 reputation score (higher is safer) alongside the full risk breakdown.

GET/api/v1/scam/phone/{number}

Look up the scam reputation of a phone number

Authentication:Bearer Token

Parameter	Type	Required	Description
`number`	string	Required	The phone number to check, supplied as a path segment (URL-encode the leading + as %2B). Example: %2B18005550199

curl -X GET "https://guard.orbai.world/api/v1/scam/phone/%2B18005550199" \
  -H "Authorization: Bearer YOUR_TOKEN"

200Phone reputation result

{
  "phone_number": "+18005550199",
  "reputation_score": 18,
  "is_scam": true,
  "is_suspicious": true,
  "risk_score": 0.82,
  "scam_type": "tech_support",
  "severity": "high",
  "explanation": "Number associated with multiple tech-support scam reports.",
  "indicators": ["multiple scam reports", "spoofed caller ID pattern"]
}

Report a Scam

Submit a confirmed scam back to OrbGuard to strengthen community protection. Reports feed the engine's pattern library and phone-reputation database.

POST/api/v1/scam/report

Report confirmed scam content (text, URL, or phone)

Authentication:Bearer Token

Parameter	Type	Required	Description
`content`	string	Optional	The scam content (message text). At least one of content, phone_number, or url is required.
`content_type`	string	Optional	The type of the reported content (e.g. text, url, phone).
`scam_type`	string	Optional	The scam category (e.g. phishing, lottery, tech_support).
`phone_number`	string	Optional	The scammer's phone number, if applicable.
`url`	string	Optional	The scam URL, if applicable.
`description`	string	Optional	Free-text notes describing the scam.
`device_id`	string	Optional	Reporting device identifier.

curl -X POST https://guard.orbai.world/api/v1/scam/report \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content_type": "text",
    "content": "You won a free iPhone! Click here to claim.",
    "scam_type": "phishing",
    "description": "Received via SMS from an unknown number"
  }'

201Report accepted

{
  "message": "Scam report submitted successfully",
  "reported_at": "2026-02-08T10:35:00Z"
}

Report a Scam Phone Number

A focused variant of the report endpoint for caller-ID and SMS-originator abuse. Reported numbers degrade the reputation score returned by the phone lookup endpoint.

POST/api/v1/scam/phone/report

Report a phone number as a scam source

Authentication:Bearer Token

Parameter	Type	Required	Description
`phone_number`	string	Required	The phone number to report, in international format.
`scam_type`	string	Optional	The scam category associated with the number.
`description`	string	Optional	Free-text notes about the call or message.
`device_id`	string	Optional	Reporting device identifier.

curl -X POST https://guard.orbai.world/api/v1/scam/phone/report \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+18005550199",
    "scam_type": "tech_support",
    "description": "Robocall claiming to be Microsoft support"
  }'

201Phone report accepted

{
  "message": "Phone number report submitted",
  "reported_at": "2026-02-08T10:36:00Z"
}

Pair With On-Device SMS Scanning

In the OrbVPN apps, scam detection runs continuously on incoming SMS and links via the SMS Protection module, calling this same engine. Cloud analysis enriches the on-device verdict with the latest community-reported patterns.

AI-Powered Scam Detection

One Endpoint, Every Content Type

How Image and Voice Work

Analyze a Text Message

Analyze a URL

Analyze an Image (Base64)

Analyze a Voice Recording (Base64)

Scam Types

Analysis Methods

Scam Pattern Library

Phone Number Reputation

Report a Scam

Report a Scam Phone Number

Pair With On-Device SMS Scanning

On this page