API
Call FraudKite from your own applications. Every example below shows a real request and the response the API returned, in curl, PowerShell, JavaScript and Python. The complete specification is available as OpenAPI 3 and in the interactive Swagger UI.
Getting started
Base URL: the address of this page. All endpoints are under /api/v1/, and every response is JSON.
Authentication: create an API key under Admin → API keys and send it in the X-API-Key header (or Authorization: Bearer tg_…). The secret is shown only once, and only its hash is stored. Each key has its own permissions, rate limit, optional source-IP allowlist and expiry date.
Single IP lookups also work without a key (30 per minute per client IP) when public lookups are enabled. Batch, phone and email checks always need a key.
export TEMPGUARD_URL=https://tempguard.example
export TEMPGUARD_KEY=tg_xxxxxxxxxxxx_your-secret # Admin → API keys$env:TEMPGUARD_URL = "https://tempguard.example"
$env:TEMPGUARD_KEY = "tg_xxxxxxxxxxxx_your-secret" # Admin → API keysPermissions
| Permission | Allows |
|---|---|
| lookup:read | GET /ip/{ip}, GET /ip/me, POST /check (IP only) |
| lookup:phone | POST /check with a phone number |
| lookup:batch | POST /ip/batch |
| email:check | POST /email/check, GET /email/domain/{domain}, email in POST /check |
| email:batch | POST /email/batch |
| velocity:global | "velocity_scope": "global" on POST /check |
| history:read, email:history | The key's own lookup history (GET /lookups, GET /email/lookups) |
Look up an IP
GET/api/v1/ip/{ip}
Returns location, network owner, network type, VPN/proxy/Tor/hosting/relay/crawler/abuse indicators with their confidence, and an explainable risk score. Permission lookup:read, or anonymous.
Optional ?verify_crawler=true runs forward-confirmed reverse DNS for search-engine crawlers (Google, Bing, Apple and others).
curl -s "$TEMPGUARD_URL/api/v1/ip/185.220.101.1" \
-H "X-API-Key: $TEMPGUARD_KEY"{
"ip": "185.220.101.1",
"ip_version": 4,
"classification": {
"class": "public",
"name": "Public",
"is_public": true,
"is_bogon": false
},
"location": {
"country_code": "DE",
"country_name": "Germany",
"continent_code": "EU",
"region": "Brandenburg",
"region_code": "BB",
"city": "Brandenburg an der Havel",
"postal_code": "14621",
"time_zone": "Europe/Berlin",
"latitude": 52.6171,
"longitude": 13.1207,
"accuracy_radius_km": 20,
"source": ""
},
"network": {
"asn": 60729,
"organization": "Stiftung Erneuerbare Freiheit",
"isp": "Stiftung Erneuerbare Freiheit",
"cidr": "185.220.101.0/24",
"type": "unknown",
"type_confidence": 0,
"type_source": ""
},
"signals": {
"vpn": {
"detected": true,
"confidence": 0.5,
"sources": []
},
"proxy": {
"detected": false,
"confidence": 0,
"sources": []
},
"tor": {
"detected": true,
"confidence": 0.95,
"sources": []
},
"hosting": {
"detected": false,
"confidence": 0,
"sources": []
},
"relay": {
"detected": false,
"confidence": 0,
"sources": []
},
"crawler": {
"detected": false,
"confidence": 0,
"sources": []
},
"abuse": {
"detected": false,
"confidence": 0,
"sources": []
},
"threat_intel": {
"detected": false,
"confidence": 0,
"sources": []
},
"allowlisted": false,
"denylisted": false,
"trusted_corporate": false
},
"risk": {
"score": 100,
"level": "critical",
"ruleset_version": 5,
"reasons": [
{
"rule_id": "tor_exit",
"rule_name": "Tor exit node",
"signal": "tor_exit",
"weight": 80,
"action": "add",
"confidence": 0.95,
"sources": []
},
{
"rule_id": "vpn_low_confidence",
"rule_name": "Lower-confidence VPN feed",
"signal": "vpn",
"weight": 35,
"action": "add",
"confidence": 0.5,
"sources": []
}
]
},
"datasets": [],
"warnings": [],
"disclaimer": "VPN, proxy and hosting detection is based on published and administrator-supplied data and heuristics. A match is evidence, not proof; the absence of a match does not mean an address is clean. Location data is approximate.",
"cached": false,
"generated_at": "2026-11-20T19:50:29.363414543Z"
}IPv6
GET/api/v1/ip/{ip}
The same endpoint accepts IPv6 and returns "ip_version": 6. Free VPN, proxy and Tor feeds cover IPv6 poorly, so warnings names every loaded feed with no IPv6 data. For those feeds, “no match” is not evidence.
NAT64 (64:ff9b::/96), 6to4 (2002::/16) and Teredo (2001::/32) addresses are analysed through the IPv4 host they carry, reported in classification.embedded_ipv4.
curl -s "$TEMPGUARD_URL/api/v1/ip/2a01:4f8:c17:1::1" \
-H "X-API-Key: $TEMPGUARD_KEY"{
"ip": "2a01:4f8:c17:1::1",
"ip_version": 6,
"classification": {
"class": "public",
"name": "Public",
"is_public": true,
"is_bogon": false
},
"location": {
"country_code": "DE",
"country_name": "Germany",
"city": "Falkenstein",
"time_zone": "Europe/Berlin",
"source": ""
},
"network": {
"asn": 24940,
"organization": "Hetzner Online GmbH",
"isp": "Hetzner Online GmbH",
"cidr": "2a01:4f8::/31",
"type": "hosting",
"type_confidence": 0.8,
"type_source": ""
},
"signals": {
"hosting": {
"detected": true,
"confidence": 0.8,
"sources": []
}
},
"risk": {
"score": 25,
"level": "medium",
"ruleset_version": 5,
"reasons": [
{
"rule_id": "hosting",
"rule_name": "Hosting/datacenter network",
"signal": "hosting",
"weight": 25,
"action": "add",
"confidence": 0.8,
"sources": [],
"detail": "Hetzner"
}
]
},
"warnings": [
"limited IPv6 coverage: some data sources contain no IPv6 entries, so the absence of a match says little about this address"
],
"datasets": []
}Caller's own IP
GET/api/v1/ip/me
Looks up the address the request came from. The response has the same shape as Look up an IP.
Forwarding headers (X-Forwarded-For, X-Real-IP, CF-Connecting-IP) are trusted only from configured proxies, so clients cannot fake their address. Called from a private network, the endpoint correctly reports a private address instead of a risk score.
curl -s "$TEMPGUARD_URL/api/v1/ip/me"{
"error": {
"code": "non_public_address",
"message": "10.0.0.0/8 is a private address and is excluded from public risk analysis",
"classification": {
"class": "private",
"prefix": "10.0.0.0/8",
"name": "Private-use",
"rfc": "RFC 1918"
}
}
}Batch lookups
POST/api/v1/ip/batch
Up to 100 addresses per request (setting lookup.batch_max). Each address counts against the key's rate limit. Results come back in input order. An invalid or private address gets its own error entry instead of failing the whole batch. Permission lookup:batch.
curl -s -X POST "$TEMPGUARD_URL/api/v1/ip/batch" \
-H "X-API-Key: $TEMPGUARD_KEY" \
-H "Content-Type: application/json" \
-d '{"ips":["8.8.8.8","185.220.101.1","10.0.0.1","not-an-ip"]}'{
"results": [
{
"input": "8.8.8.8",
"result": {
"ip": "8.8.8.8",
"ip_version": 4,
"classification": {
"class": "public",
"is_public": true,
"is_bogon": false
},
"location": {
"country_code": "US"
},
"network": {
"asn": 15169,
"organization": "Google LLC",
"type": "hosting"
},
"signals": {
"hosting": {
"detected": true,
"confidence": 0.8
}
},
"risk": {
"score": 25,
"level": "medium"
},
"datasets": []
}
},
{
"input": "185.220.101.1",
"result": {
"ip": "185.220.101.1",
"ip_version": 4,
"classification": {
"class": "public",
"is_public": true,
"is_bogon": false
},
"location": {
"country_code": "DE",
"city": "Brandenburg an der Havel"
},
"network": {
"asn": 60729,
"organization": "Stiftung Erneuerbare Freiheit",
"type": "unknown"
},
"signals": {
"vpn": {
"detected": true,
"confidence": 0.5
},
"tor": {
"detected": true,
"confidence": 0.95
}
},
"risk": {
"score": 100,
"level": "critical"
},
"datasets": []
}
},
{
"input": "10.0.0.1",
"result": {
"ip": "10.0.0.1",
"ip_version": 4,
"classification": {
"class": "private",
"is_public": false,
"is_bogon": true
},
"network": {
"asn": null,
"type": "unknown"
},
"signals": {},
"risk": null,
"datasets": []
}
},
{
"input": "not-an-ip",
"error": {
"code": "invalid_ip",
"message": "invalid IP address"
}
}
]
}IP + phone + email
POST/api/v1/check
Scores an IP together with an optional phone number and email address, typical for sign-up or checkout checks. The response is the IP result plus phone and email objects. risk combines all evidence: here a disposable email domain plus a phone/IP country mismatch (Bulgarian phone, Hong Kong IP).
Velocity: the check also counts how many different phones, emails and IPs appear together (same IP, same /24 network, same phone, same email), to detect someone probing your form. The result's velocity object shows the counts. Add "velocity": false to exclude a request (tests, re-checks, imports), or "velocity": true to apply it even when it is switched off in Settings. By default all keys of your account are counted together; "velocity_scope": "api_key" counts only this key, and "global" (everyone) needs the velocity:global permission.
Phone numbers must be in international format (+359…); they are never stored in raw form. Permissions: lookup:read, plus lookup:phone for a phone and email:check for an email.
curl -s -X POST "$TEMPGUARD_URL/api/v1/check" \
-H "X-API-Key: $TEMPGUARD_KEY" \
-H "Content-Type: application/json" \
-d '{"ip":"1.36.0.1","phone":"+359881234567","email":"[email protected]"}'{
"ip": "1.36.0.1",
"ip_version": 4,
"location": {
"country_code": "HK",
"country_name": "Hong Kong"
},
"network": {
"asn": 4760,
"organization": "HKT Limited",
"type": "unknown"
},
"phone": {
"valid": true,
"possible": true,
"country_code": "BG",
"calling_code": 359,
"type": "mobile",
"risky_type": false,
"carrier": "A1",
"masked": "+359 •••••••67",
"is_disposable": false,
"ip_country": "HK",
"country_mismatch": true,
"same_region": false,
"comparison": "mismatch"
},
"email": {
"email": "[email protected]",
"classification": "disposable",
"policy_action": "block",
"is_disposable": true,
"is_free_provider": false,
"risk": {
"score": 90,
"level": "critical"
}
},
"risk": {
"score": 100,
"level": "critical",
"ruleset_version": 5,
"reasons": [
{
"rule_id": "disposable_domain_exact_match",
"rule_name": "Disposable domain (maintained list)",
"signal": "email_disposable",
"weight": 90,
"action": "add",
"confidence": 1,
"sources": [
"disposable-github",
"disposable-email-domains-community"
],
"detail": "disposable-github"
},
{
"rule_id": "phone_ip_mismatch",
"rule_name": "Phone/IP country mismatch",
"signal": "phone_ip_mismatch",
"weight": 15,
"action": "add",
"confidence": 1,
"sources": [
"phone-ip-compare"
],
"detail": "phone BG, IP HK"
}
]
}
}Email check
POST/api/v1/email/check
Checks syntax (including international domains), domain existence and mail servers (MX, null MX, A fallback), disposable, free, role (info@, sales@) and alias/relay addresses. Returns a risk score and a policy_action: allow review block.
Optional body fields check_dns and check_mx (default true). DNS proves a domain can receive email, not that the mailbox exists. Permission email:check.
curl -s -X POST "$TEMPGUARD_URL/api/v1/email/check" \
-H "X-API-Key: $TEMPGUARD_KEY" \
-H "Content-Type: application/json" \
-d '{"email":"[email protected]"}'{
"email": "[email protected]",
"normalized_email": "[email protected]",
"local_part": "user",
"domain": "mailinator.com",
"ascii_domain": "mailinator.com",
"valid_syntax": true,
"domain_exists": true,
"has_mx_records": true,
"accepts_email": true,
"mailbox_exists": null,
"is_disposable": true,
"is_free_provider": false,
"is_role_address": false,
"is_alias_or_relay": false,
"is_catch_all": null,
"classification": "disposable",
"policy_action": "block",
"provider": {
"name": null,
"category": "disposable"
},
"risk": {
"score": 90,
"level": "critical",
"ruleset_version": 5,
"reasons": [
{
"code": "DISPOSABLE_DOMAIN_EXACT_MATCH",
"rule_id": "disposable_domain_exact_match",
"signal": "email_disposable",
"weight": 90,
"description": "The email domain appears in a maintained disposable-email list.",
"confidence": 1,
"sources": []
}
]
},
"dns": {
"status": "valid",
"checked": true,
"domain_exists": true,
"has_mx_records": true,
"accepts_email": true,
"mx": [
{
"priority": 1,
"hostname": "mail.mailinator.com"
},
{
"priority": 1,
"hostname": "mail2.mailinator.com"
}
],
"null_mx": false,
"fallback_a_record": false,
"dnssec_validated": false,
"ttl_seconds": 154
},
"disposable_match": {
"matched_domain": "mailinator.com",
"match_type": "exact",
"source": "",
"confidence": 1,
"has_active_mx": true
},
"matches": [
{
"provider_id": "",
"list": "",
"classification": "disposable",
"matched_domain": "mailinator.com",
"match_type": "exact",
"confidence": 1
},
{
"provider_id": "",
"list": "",
"classification": "disposable",
"matched_domain": "mailinator.com",
"match_type": "exact",
"confidence": 0.95
}
],
"sources": [],
"warnings": [],
"disclaimer": "Syntax, DNS and MX checks show whether a domain can receive email; they do not prove that the mailbox exists. Disposable classification is based on maintained public lists and administrator overrides.",
"cached": true,
"processed_at": "2026-11-20T19:50:29.397476536Z"
}{
"email": "[email protected]",
"normalized_email": "[email protected]",
"domain": "gmail.com",
"valid_syntax": true,
"domain_exists": true,
"has_mx_records": true,
"accepts_email": true,
"mailbox_exists": null,
"is_disposable": false,
"is_free_provider": true,
"is_role_address": false,
"is_alias_or_relay": false,
"classification": "free",
"policy_action": "allow",
"provider": {
"name": "gmail.com",
"category": "free"
},
"risk": {
"score": 0,
"level": "low",
"ruleset_version": 5,
"reasons": [
{
"code": "FREE_EMAIL_PROVIDER",
"rule_id": "free_email_provider",
"signal": "email_free",
"weight": 0,
"description": "Free webmail provider (informational).",
"confidence": 1,
"sources": [
"free-email-domains"
]
}
]
},
"dns": {
"status": "valid",
"mx": [
{
"priority": 5,
"hostname": "gmail-smtp-in.l.google.com"
},
{
"priority": 10,
"hostname": "alt1.gmail-smtp-in.l.google.com"
},
{
"priority": 20,
"hostname": "alt2.gmail-smtp-in.l.google.com"
},
{
"priority": 30,
"hostname": "alt3.gmail-smtp-in.l.google.com"
},
{
"priority": 40,
"hostname": "alt4.gmail-smtp-in.l.google.com"
}
]
}
}Email batch
POST/api/v1/email/batch
Up to 100 addresses (setting email.batch_max). Each counts against the rate limit. Permission email:batch.
curl -s -X POST "$TEMPGUARD_URL/api/v1/email/batch" \
-H "X-API-Key: $TEMPGUARD_KEY" \
-H "Content-Type: application/json" \
-d '{"emails":["[email protected]","[email protected]","bad"]}'{
"results": [
{
"email": "[email protected]",
"ascii_domain": "yopmail.com",
"valid_syntax": true,
"classification": "disposable",
"policy_action": "block",
"is_disposable": true,
"is_free_provider": false,
"risk": {
"score": 90,
"level": "critical"
}
},
{
"email": "[email protected]",
"ascii_domain": "gmail.com",
"valid_syntax": true,
"classification": "free",
"policy_action": "allow",
"is_disposable": false,
"is_free_provider": true,
"risk": {
"score": 0,
"level": "low"
}
},
{
"email": "bad",
"ascii_domain": "",
"valid_syntax": false,
"classification": "invalid",
"policy_action": "block",
"is_disposable": false,
"is_free_provider": false,
"risk": {
"score": 100,
"level": "critical"
},
"syntax_error": "address must contain a local part and a domain separated by @"
}
]
}Domain check
GET/api/v1/email/domain/{domain}
Classifies a domain without a mailbox name. Useful to vet a domain list. Permission email:check.
curl -s "$TEMPGUARD_URL/api/v1/email/domain/addy.io" \
-H "X-API-Key: $TEMPGUARD_KEY"{
"domain": "addy.io",
"ascii_domain": "addy.io",
"domain_exists": true,
"has_mx_records": true,
"is_disposable": true,
"is_alias_or_relay": false,
"classification": "disposable",
"policy_action": "review",
"provider": {
"name": null,
"category": "disposable"
},
"risk": {
"score": 40,
"level": "medium",
"ruleset_version": 5,
"reasons": [
{
"code": "LOW_CONFIDENCE_LIST_MATCH",
"rule_id": "low_confidence_list_match",
"signal": "email_disposable",
"weight": 40,
"description": "The domain appears only in a lower-confidence or strict list.",
"confidence": 0.85,
"sources": [
"valid-email-checker"
]
}
]
},
"dns": {
"status": "valid",
"mx": [
{
"priority": 10,
"hostname": "mx1.addy.io"
},
{
"priority": 20,
"hostname": "mx2.addy.io"
}
]
},
"matches": [
{
"provider_id": "valid-email-checker",
"list": "valid-email-checker",
"classification": "disposable",
"matched_domain": "addy.io",
"match_type": "exact",
"confidence": 0.85,
"version": "20261120T1943Z-8c74cb4a",
"updated_at": "2026-11-20T19:43:28.428108965Z"
}
]
}Reading a result
Risk score and level
- low 0–24
- medium 25–49
- high 50–74
- critical 75–100
risk.reasons lists every rule that contributed: its weight, confidence and, where useful, a detail. Rules and weights are configured by administrators; ruleset_version identifies the rules used.
Signals are evidence, not verdicts
- Each indicator in
signalshasdetectedand aconfidence(0–1). Data-source names, matched networks and dataset versions (sources,matches,datasets) are internal: the fields are present but empty. - Hosting is not malicious by itself, and verified crawlers score 0.
- No match does not mean an address is clean: VPN and proxy detection is never certain.
- Check
warnings, e.g. temporarily missing data or limited IPv6 coverage. - Every response carries an
X-Request-Idheader; quote it when reporting a problem.
Errors
Errors use one format: {"error": {"code": "…", "message": "…"}}. Branch on code; the message is human-readable and may change.
| Status | Codes | Meaning |
|---|---|---|
| 400 | invalid_ip, invalid_phone, invalid_domain, invalid_json, invalid_request, empty_batch | Bad input |
| 401 | authentication_required | This endpoint needs an API key |
| 401 | invalid_credentials | Unknown, expired or revoked API key |
| 403 | forbidden | The key lacks the required permission |
| 403 | source_ip_not_allowed | The caller is outside the key's source-IP allowlist |
| 413 | batch_too_large, body_too_large | Too many items, or request body too large |
| 415 | unsupported_media_type | POST without Content-Type: application/json |
| 422 | non_public_address | Private, loopback, documentation or other special-purpose address (not risk-scored) |
| 429 | rate_limited | Rate limit reached; wait Retry-After seconds |
{
"error": {
"code": "invalid_ip",
"message": "invalid IP address"
}
}{
"error": {
"code": "non_public_address",
"message": "10.0.0.0/8 is a private address and is excluded from public risk analysis",
"classification": {
"class": "private",
"prefix": "10.0.0.0/8",
"name": "Private-use",
"rfc": "RFC 1918"
}
}
}{
"error": {
"code": "authentication_required",
"message": "email checks require an API key or a session"
}
}{
"error": {
"code": "rate_limited",
"message": "rate limit exceeded; retry later",
"retry_after_seconds": 31
}
}Rate limits
Limits are per minute: 30 for anonymous callers (per client IP; IPv6 clients per /64), 600 per API key unless the key has its own limit. Every response reports the remaining budget; a 429 adds Retry-After. Batch requests cost one unit per item.
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Ratelimit-Limit: 30
Ratelimit-Remaining: 29
Ratelimit-Reset: 31
X-Request-Id: 5ffa1c341c3712cc6a9dac15HTTP/1.1 429 Too Many Requests
Content-Type: application/json; charset=utf-8
Ratelimit-Limit: 30
Ratelimit-Remaining: 0
Ratelimit-Reset: 31
Retry-After: 31
X-Request-Id: 83538938ea608fe8d7e82f91On 429, wait Retry-After seconds before retrying. For bulk work, use the batch endpoints and spread requests over time, or ask an administrator for a key with a higher limit.