Antifrauder API · v1

Fraud-check API

A single REST API to score the risk of a phone, email, IP address or device fingerprint. Each call returns a normalized result, a 0–100 fraud score with the signals behind it, and the exact amount charged.

BASE https://antifrauder.app + /api/v1/…

All requests are JSON over HTTPS. Every endpoint is authenticated with an API key and billed against your prepaid balance. Pick a check type from the left to see its request and response in full.

Phone →

Validity, carrier, line type, connectivity — multi-source consensus + score.

Email →

Deliverability, disposable / catch-all, domain trust, breaches, identity.

IP →

VPN / proxy / Tor / bot detection, geolocation, ASN, abuse history.

Fingerprint →

Browser-side device scan: spoofing, incognito, bot & velocity signals.

Authentication

Authenticate every request with your secret key in the X-API-Key header. Generate and rotate the key in the Antifrauder mini-app → API key.

HTTP

X-API-Key: sk_live_a1b2c3d4e5f6...

The API is gated behind a funded balance. Every request — including read-only ones — requires a balance greater than zero. A key with a zero balance returns 402 insufficient_balance on every route.

Failure	Status	Code
Missing or unknown key	401	`invalid_api_key`
Balance is zero	402	`insufficient_balance`

Balance

Checks are prepaid. You top your balance up in the mini-app; each check is debited from it. Phone and email have two tiers (basic / extended); IP and device are single-tier.

You are charged once per check, before it runs. If every provider fails, the charge is automatically refunded and the call returns 502 provider_failed.
Set use_storage: true to reuse your own previous result for the same value at an equal-or-higher tier — that response is free (charged: 0, fromStorage: true).
Every check response carries the amount debited (charged) and your new balance.

Rate limiting

Requests are rate-limited per API key. Exceeding the limit returns 429 rate_limited; retry after a short backoff. The default budget is 60 requests / minute (your plan may differ).

Idempotency

Check endpoints (the POST /api/v1/check/* routes) accept an optional Idempotency-Key header. Re-sending the same key with the same request returns the stored response without charging again — safe for retries on network failures. The replay window is 24 hours.

Situation	Result
Same key, same request, within 24h	Returns the original response, no new charge
Same key, different request body	409 `idempotency_conflict`

HTTP

Idempotency-Key: 7e3b1c9a-2f44-4d10-9a8e-c0ffee000001

Errors

Errors use standard HTTP status codes and a uniform JSON body: { "error": "...", "code": "..." }. Always branch on the stable code, not the human-readable error text.

402 — JSON

{
  "error": "insufficient balance",
  "code": "insufficient_balance",
  "required": 22,
  "balance": 8
}

Status	Code	Meaning
400	`invalid_target`	The phone / email / IP could not be parsed.
400	`device_requires_browser`	Device checks can't run over JSON — use the fingerprint embed.
401	`invalid_api_key`	Missing or unknown `X-API-Key`.
402	`insufficient_balance`	Balance too low for this check (carries `required` + `balance`).
404	`not_found`	No stored result for this value / id.
409	`idempotency_conflict`	Idempotency-Key reused with a different body.
429	`rate_limited`	Per-key rate limit exceeded.
502	`provider_failed`	All upstream providers failed; the charge was refunded.

Account endpoint

Read your live balance and remaining free quota.

GET /api/v1/account

cURL

curl https://antifrauder.app/api/v1/account \
  -H "X-API-Key: $ANTIFRAUDER_KEY"

200 — JSON

{
  "balance": 4820,
  "freeRemaining": 0
}

Field	Type	Description
`balance`	integer	Current balance, in cents.
`freeRemaining`	integer	Free interactive checks left today (API surface is always paid).