API Documentation — FraudIntel India

Overview

The FraudIntel API lets you check any phone number, UPI ID, email, domain, or crypto wallet against India's largest crowd-sourced fraud intelligence database. Average response time under 200ms — fast enough for pre-transaction screening.

India-first signals. The API covers Digital Arrest, KBC Lottery, TRAI scams, UPI mule accounts, and Hindi-language fraud patterns that global fraud APIs don't detect.

Recommendation, not block. The API returns a risk recommendation. Your system decides whether to block or flag. We never hard-block transactions on your behalf.

Authentication

All API endpoints require an API key passed in the X-API-Key header. Get your key at fraudintel.in/dashboard → Settings.

REQUEST HEADERS

X-API-Key: fi_live_your_api_key_here
Content-Type: application/json

Key formats: Live keys start with fi_live_. Rotate your key instantly from the dashboard if compromised. Keys are hashed before storage — we can't recover a lost key.

Rate Limits

ENDPOINT GROUP	LIMIT	WINDOW
All API endpoints (global)	300 requests	15 minutes
Auth endpoints (/auth/*)	20 requests	15 minutes
Sensitive endpoints	5 requests	15 minutes

Rate limit headers are returned on every response:

RATE LIMIT HEADERS

X-RateLimit-Limit:     300
X-RateLimit-Remaining: 299
X-RateLimit-Reset:     1714204800  ← Unix timestamp

If you exceed the limit, you'll receive a 429 Too Many Requests with a Retry-After header. Enterprise plans have higher limits — contact us.

Check Entity

GET /v1/check-entity

Check any entity — phone number, UPI ID, email address, domain, or crypto wallet — against the fraud database. This is the primary endpoint for pre-transaction screening.

QUERY PARAMETERS

PARAMETER	TYPE	REQUIRED	DESCRIPTION
q	string	required	The entity to check. Phone: `9876543210` · UPI: `user@paytm` · Domain: `sbi-kyc.in` · Email: `scam@gmail.com`

REQUEST

CURL

GET https://www.fraudintel.in/v1/check-entity?q=suspect@paytm
X-API-Key: fi_live_your_key

RESPONSES

200 · SUCCESS

{
  "risk":            "HIGH",           // HIGH | MEDIUM | LOW | CLEAN
  "score":           0.91,            // 0.0 – 1.0
  "times_reported":  14,              // crowd-sourced report count
  "in_entity_db":   true,           // in our fraud entity database
  "verified":        true,           // verified by our team or gov source
  "category":        "upi_fraud",
  "signals": ["upi_fraud", "mule_account", "kbc_scam"],
  "first_seen":      "2025-11-02",
  "last_seen":       "2026-03-17",
  "recommendation": "BLOCK",        // BLOCK | FLAG | MONITOR | ALLOW
  "audit_id":        "fi_log_a1b2c3d4" // for dispute/review
}

401 · UNAUTHORIZED

{ "error": "Invalid or missing API key" }

429 · RATE LIMITED

{ "error": "Rate limit exceeded", "retry_after": 847 }

Check Phone Number

GET /v1/check-phone

Check a specific Indian phone number against fraud reports. Equivalent to /v1/check-entity?q={phone} but with phone-specific validation.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
phone	string	required	10-digit Indian mobile number. With or without country code (+91).

CURL

GET https://www.fraudintel.in/v1/check-phone?phone=9876543210
X-API-Key: fi_live_your_key

Check UPI ID

GET /v1/check-upi

Check a UPI Virtual Payment Address (VPA) against fraud reports. Use this before processing collect requests or before allowing a beneficiary to be added.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
upi	string	required	UPI Virtual Payment Address. Examples: `user@paytm`, `9876543210@ybl`, `shop@okaxis`

CURL

GET https://www.fraudintel.in/v1/check-upi?upi=suspect@paytm
X-API-Key: fi_live_your_key

Scan URL / Domain

GET /v1/scan-url

Scan a URL or domain for phishing signals, fake banking portals, and scam indicators. Checks domain age, WHOIS data, and our fraud database. Does not require an API key for public checks.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
url	string	required	Full URL or domain. Examples: `https://sbi-kyc-update.in` or `hdfc-reward-claim.com`

CURL

GET https://www.fraudintel.in/v1/scan-url?url=https://sbi-kyc-update.in
X-API-Key: fi_live_your_key

200 · SUCCESS

{
  "domain":      "sbi-kyc-update.in",
  "risk_level":  "HIGH",
  "risk_score":  87,
  "reasons": [
    "Domain impersonates SBI (State Bank of India)",
    "Registered 3 days ago — suspicious recency",
    "Reported in CERT-In phishing advisories"
  ]
}

Analyze Text

POST /v1/analyze

Analyze any text message for fraud signals. Useful for screening WhatsApp messages, SMS, emails, or chat content before acting on them. Supports English and Hindi.

REQUEST BODY

FIELD	TYPE	REQUIRED	DESCRIPTION
text	string	required	The message text to analyze. Max 5,000 characters.

CURL

POST https://www.fraudintel.in/v1/analyze
X-API-Key: fi_live_your_key
Content-Type: application/json

{
  "text": "Send OTP to claim KBC prize of 50 lakh urgently"
}

200 · SUCCESS

{
  "risk_score":  85,
  "risk_level":  "HIGH",
  "category":    "lottery_scam",
  "explanation": "Classic KBC lottery scam requesting OTP",
  "signals": ["kbc_scam", "otp_request", "urgency", "large_prize_claim"],
  "entities": {
    "phones":  [],
    "upi_ids": [],
    "emails":  [],
    "domains": []
  }
}

Get Fraud Reports

GET /v1/reports

Retrieve the latest fraud reports from the database, sorted by recency.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
limit	integer	optional	Number of reports to return. Default: 20. Max: 100.
offset	integer	optional	Pagination offset. Default: 0.
category	string	optional	Filter by category. See Fraud Signals reference below.

CURL

GET https://www.fraudintel.in/v1/reports?limit=20&offset=0
X-API-Key: fi_live_your_key

Platform Statistics

GET /v1/stats

Get aggregate platform statistics — total reports, entity counts, category breakdown.

CURL

GET https://www.fraudintel.in/v1/stats
X-API-Key: fi_live_your_key

200 · SUCCESS // sample response — live values served from DB

{
  "total_reports":   24871,
  "total_entities":  8234,
  "reports_today":   142,
  "by_category": {
    "upi_fraud":          8421,
    "digital_arrest":     3102,
    "job_scam":           2891,
    "bank_phishing":      2344,
    "investment_fraud":   1987
  }
}

API Usage

GET /v1/usage

Check your API key usage — calls today, calls this month, and remaining quota.

CURL

GET https://www.fraudintel.in/v1/usage
X-API-Key: fi_live_your_key

200 · SUCCESS

{
  "plan":              "business",
  "calls_today":       342,
  "calls_limit_daily": 5000,
  "calls_this_month":  12841,
  "resets_at":         "2026-05-01T00:00:00Z"
}

Fraud Signals Reference

The signals array in every response contains one or more of these values:

SIGNAL	DESCRIPTION
upi_fraud	UPI / payment fraud — fake collect requests, QR scams, mule accounts
digital_arrest	Fake CBI/TRAI/ED officer threatening arrest via video call
kbc_scam	KBC lottery / prize scam — requests OTP or fee to claim prize
trai_scam	Fake TRAI number disconnection threat
mule_account	Bank account or UPI used to launder fraud proceeds
bank_phishing	Impersonates SBI, HDFC, ICICI, Axis, or other banks
kyc_fraud	Fake KYC update request to steal credentials
otp_request	Explicitly requests OTP — strong fraud signal
fake_job_offer	WFH / task-based job scam — initial payment then disappear
loan_scam	Fake loan app or advance fee loan fraud
investment_fraud	Fake trading platform, stock tips, crypto guaranteed returns
crypto_scam	Crypto wallet fraud, pig butchering, fake exchange
government_impersonation	Impersonates RBI, IT Dept, police, EPFO
phishing_link	URL is a phishing page
sim_swap	Linked to SIM swap fraud reports
hindi_otp_request	Hindi-language OTP request pattern detected
hindi_urgency	Hindi-language urgency pattern — common in fraud scripts

Risk Levels & Recommendations

RISK	SCORE RANGE	RECOMMENDATION	MEANING
HIGH	0.70 – 1.00	BLOCK	Strong fraud signals. 3+ reports, verified, or confirmed by government source.
MEDIUM	0.40 – 0.69	FLAG	Some signals present. 1–2 reports or AI detection without DB confirmation.
LOW	0.10 – 0.39	MONITOR	Weak signals. Treat with caution — may be new or emerging fraud pattern.
CLEAN	0.00 – 0.09	ALLOW	Not in database. No signals detected. Not a guarantee of safety.

CLEAN ≠ Safe. A CLEAN result means no reports yet — not that the entity is guaranteed legitimate. New scammer numbers return CLEAN until first reported. Always use judgment alongside the score.

Plans & Rate Limits

PLAN	CALLS / DAY	FEATURES	SUPPORT
Developer	100	V1 + V2 endpoints, velocity scoring	Community
Startup	2,000	All endpoints, webhook alerts, bulk scan	Email · 48hr
Growth	20,000	ML scoring, network graph, case dashboard	Email · 24hr
Enterprise	Unlimited	Dedicated instance, custom models, SLA	Dedicated · 4hr SLA

Pricing is customised based on transaction volume and use case. Contact us to discuss your requirements.

Get API Access → Free Dashboard →

V2 — ML Mule Score NEW

Full ML-powered mule behaviour score for a single UPI ID. Combines blacklist DB + velocity engine + 10-feature behavioural model. Returns BLOCK / REVIEW / ALLOW decision in under 200ms.

POST /v2/mule-score

Score a single UPI ID across all 3 detection layers simultaneously.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
upi_id	string	required	UPI Virtual Payment Address to score. e.g. 9876543210@paytm

CURL

POST https://www.fraudintel.in/v2/mule-score
X-API-Key: fi_live_your_key
Content-Type: application/json

{
  "upi_id": "9876543210@paytm"
}

200 OK — ML Score Response // sample response

{
  "request_id": "uuid-v4",
  "api_version": "2.0",
  "status": "success",
  "data": {
    "upi_id":     "9876543210@paytm",
    "risk_score":  78,             ← 0–100 ML score
    "risk_level":  "HIGH",         ← HIGH / MEDIUM / LOW / CLEAN
    "action":      "BLOCK",        ← BLOCK / REVIEW / ALLOW
    "signals":     ["burst_credits", "passthrough_mule"],
    "velocity":    {
      "credit_count":     14,
      "debit_count":      12,
      "burst_10m":        7,
      "passthrough_pct":  85,
      "unique_senders":   11
    },
    "database":    { "blacklist_hits": 0, "report_mentions": 2 },
    "network_degree": 3
  },
  "meta": { "processed_ms": 143, "model_version": "fraudintel-ml-v1" }
}

POST /v2/mule-score/bulk

Score up to 200 UPI IDs in a single request. Results sorted by risk score descending.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
upi_ids	string[]	required	Array of UPI IDs to score. Maximum 200 per request.

CURL

POST https://www.fraudintel.in/v2/mule-score/bulk
X-API-Key: fi_live_your_key

{
  "upi_ids": ["id1@paytm", "id2@ybl", "id3@okicici"]
}

200 OK — Bulk Score Response // sample response

{
  "data": {
    "results": [
      { "upi_id": "id1@paytm", "risk_score": 82, "risk_level": "HIGH", "action": "BLOCK" },
      { "upi_id": "id2@ybl",   "risk_score":  45, "risk_level": "MEDIUM", "action": "REVIEW" },
      { "upi_id": "id3@okicici", "risk_score":  5, "risk_level": "CLEAN", "action": "ALLOW" }
    ],
    "scanned":   3,
    "flagged":   2,
    "high_risk": 1
  }
}

POST /v2/transaction-risk

Enhanced transaction risk — records the event into the velocity engine and returns a combined risk score. Use this during payment processing for real-time screening.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
upi_id	string	required	UPI VPA of the account to screen.
amount	number	optional	Transaction amount in ₹. Adds amount-based risk boost for large values.
direction	string	optional	"credit" or "debit" — records event for velocity tracking.
counterparty_upi	string	optional	The other side of the transfer. Used for round-trip detection.

CURL

POST https://www.fraudintel.in/v2/transaction-risk
X-API-Key: fi_live_your_key

{
  "upi_id":           "9876543210@paytm",
  "amount":           25000,
  "direction":        "credit",
  "counterparty_upi": "sender@ybl"
}

200 OK — Transaction Risk Response // sample response

{
  "data": {
    "upi_id":       "9876543210@paytm",
    "risk_score":   65,
    "risk_level":   "MEDIUM",
    "action":       "REVIEW",
    "signals":      ["burst_credits", "high_value_credits"],
    "recommendation": "Flag for manual review. Suspicious velocity patterns detected."
  }
}

POST /v2/webhooks/register

Register a webhook URL to receive real-time push alerts when a HIGH risk account is detected. Your endpoint must be HTTPS and return 2xx within 10 seconds.

PARAMETER	TYPE	REQUIRED	DESCRIPTION
url	string	required	HTTPS URL to POST alert payloads to.
events	string[]	optional	Event types to subscribe to. Default: ["high_risk"]. Options: high_risk, mule_detected, burst_alert.
secret	string	optional	HMAC secret for payload signature verification.

WEBHOOK PAYLOAD

{
  "event":       "high_risk",
  "timestamp":   "2026-05-30T10:00:00.000Z",
  "api_version": "2.0",
  "data": {
    "upi_id":  "mule123@ybl",
    "score":   91,
    "signals": ["burst_credits", "passthrough_mule", "ml_high_mule_probability"]
  }
}

Retry policy: Failed deliveries are retried 3 times with exponential backoff (2s, 4s, 8s). All delivery attempts logged in webhook_deliveries.

Velocity Signal Reference NEW

Signals detected by the V2 velocity engine. Returned in the signals[] array of all V2 responses.

SIGNAL	DESCRIPTION	WEIGHT
burst_credits	5+ credit transactions received in a 10-minute window	+35
passthrough_mule	70%+ of incoming credits debited out within 5 minutes	+40
smurfing_pattern	10+ unique senders transferring to one account in 24 hours	+35
round_trip	Funds cycling — account debits to accounts it also received from	+40
dormancy_spike	Account inactive 30+ days then suddenly receives 5+ credits	+30
high_volume_credits	20+ credit transactions in 24 hours	+25
high_value_credits	Total incoming credits exceed ₹1 lakh in 24 hours	+20
ml_high_mule_probability	ML model score ≥70 — combined feature analysis flags high mule probability	auto

Changelog

May 2026

V2 ML Engine — Velocity + Behavioural Scoring

Launched V2 API with 3-layer intelligence: blacklist DB + velocity engine + ML behavioural scorer. BLOCK/REVIEW/ALLOW decisions in under 200ms. Bulk scoring up to 200 UPI IDs per request.

Apr 2026

Webhook Engine + Real-Time Alerts

Added webhook registration for push alerts on HIGH risk detections. 3-attempt retry with exponential backoff. Full delivery logging in webhook_deliveries table.

Mar 2026

Velocity Engine — Transaction Pattern Detection

Launched real-time velocity scoring. Detects burst credits, pass-through mule behaviour, smurfing, dormancy spikes, and round-trip patterns across 24-hour rolling windows.

Feb 2026

Network Graph Analysis

Added graph-based entity relationship engine. Detects fraud clusters by connecting UPI IDs, phone numbers, emails, and domains that appear across multiple reports.

Jan 2026

AI Classification Engine

Launched Ollama-powered fraud classification. 15 fraud category taxonomy covering UPI fraud, KBC scams, digital arrest, job scams, crypto fraud, and more. Rule-based fallback for zero-latency responses.

Dec 2025

V1 API Launch

Public launch of V1 endpoints — UPI blacklist lookup, bulk scan (200 IDs), transaction risk scoring, fraud report submission. API key authentication, rate limiting, and audit logging live.