API Documentation

Getting started

The Scam-Less API is a JSON REST API. All requests require an API key passed in the X-API-Key header. Choose a plan below to get started instantly.

Base URL:

https://api.scam-less.com

Authentication

Include your API key in every request:

X-API-Key: your_api_key_here

Requests without a valid key return 401 Unauthorized.

Endpoints

POST /scan-text

Analyse a message (text, email, or chat) for scam patterns.

Request body

Field	Type	Required	Description
text	string	Yes	The message to analyse (5–5,000 characters)

Example request

POST /scan-text
Content-Type: application/json
X-API-Key: your_api_key

{
  "text": "Your parcel is held. Pay EUR 1.99 customs fee: bit.ly/xyz"
}

Response

{
  "verdict": "scam",
  "confidence": 91,
  "flags": ["delivery_scam", "suspicious_link"],
  "explanation": "Fake delivery fee with a phishing link.",
  "processing_ms": 820
}

Response fields

Field	Type	Description
verdict	string	scam, possible_scam, or safe
confidence	integer	0–100, how certain the analysis is
flags	array	Zero or more scam-type flags (see below)
explanation	string	Plain-English reason, safe to show to end users
processing_ms	integer	Processing time in milliseconds

Possible flags

fake_prize	suspicious_link	urgency_tactic
unknown_sender	payment_request	impersonation
phishing	delivery_scam	tax_scam
romance_scam	investment_scam	account_threat

POST /check-link

Check whether a URL is a phishing or scam link.

Request body

Field	Type	Required	Description
url	string	Yes	The URL to check

Example request

POST /check-link
Content-Type: application/json
X-API-Key: your_api_key

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

Response

{
  "verdict": "dangerous",
  "confidence": 94,
  "flags": ["lookalike_domain", "brand_impersonation"],
  "explanation": "Fake AIB login page on a lookalike domain.",
  "processing_ms": 450
}

Link verdicts are dangerous, suspicious, or safe.

GET /health

Check if the API is running. No authentication required.

GET /health

// Response
{ "status": "ok" }

GET /examples

Fetch common scam examples (useful for educational content in your UI).

GET /examples?category=delivery_scam
X-API-Key: your_api_key

// Response
{
  "examples": [
    {
      "category": "delivery_scam",
      "title": "Delivery fee scam",
      "example": "An Post: your parcel is held...",
      "tip": "Couriers don't ask for fees by text.",
      "report_count": 287
    }
  ],
  "count": 1
}

POST /check-number

Check whether a phone number and call context matches known scam-call patterns.

Request body

Field	Type	Required	Description
number	string	Yes	The phone number, ideally with country code (e.g. +353, +44)
context	string	No	What the caller said — strongly improves accuracy

Example request

POST /check-number
Content-Type: application/json
X-API-Key: your_api_key

{
  "number": "+353 87 123 4567",
  "context": "They said my AIB account was compromised and to press 1"
}

Response — same shape as /scan-text, with verdict one of scam, suspicious, or likely_safe.

POST /check-romance

Analyse a conversation for romance and investment ("pig-butchering") scam patterns. Accepts pasted text, an uploaded screenshot, or both.

Request body

Field	Type	Required	Description
message	string	Yes*	The conversation text (*required unless image is provided)
context	string	No	Background — how you met, how long you've been talking
image	string	No	Base64-encoded screenshot of the conversation (JPEG)
image_type	string	No	MIME type of the image, e.g. image/jpeg

Response — same shape as /scan-text, with verdict one of romance_scam, possible_romance_scam, or appears_genuine, plus a phase field (hook, line, or sinker) indicating how far the scam has progressed.

Error handling

Status	Meaning
400	Bad request — message too short or missing required field
401	Unauthorized — invalid or missing API key
429	Rate limited — you've exceeded your plan's scan limit
500	Server error — try again in a moment

Rate limits

Limits depend on your plan. The response includes rate-limit headers:

X-RateLimit-Limit: 2000
X-RateLimit-Remaining: 1847
X-RateLimit-Reset: 1719792000

Pricing

Simple, usage-based plans. Start free, no card required for the free tier. Prices in USD.

Need more than 50,000 scans, white-label, or on-prem? Talk to us about Enterprise.

Your API key is emailed to you immediately after payment. Start free — no card required for 100 scans/month.

Code examples

Python

import requests

r = requests.post("https://api.scam-less.com/scan-text",
    headers={"X-API-Key": "your_key"},
    json={"text": "You've won a prize! Click here."})
print(r.json()["verdict"])  # "scam"

JavaScript (fetch)

const res = await fetch("https://api.scam-less.com/scan-text", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    "X-API-Key": "your_key"
  },
  body: JSON.stringify({ text: "Verify your account now" })
});
const { verdict, explanation } = await res.json();

cURL

curl -X POST https://api.scam-less.com/scan-text \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your_key" \
  -d '{"text": "Your tax refund is ready. Click to claim."}'

Need help?

Email hello@scam-less.com for integration support, enterprise enquiries, or to request a feature.