Skip to content
FraudKite

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.

Linux / macOS / WSL (bash)
export TEMPGUARD_URL=https://tempguard.example
export TEMPGUARD_KEY=tg_xxxxxxxxxxxx_your-secret   # Admin → API keys
Windows PowerShell
$env:TEMPGUARD_URL = "https://tempguard.example"
$env:TEMPGUARD_KEY = "tg_xxxxxxxxxxxx_your-secret"   # Admin → API keys

Permissions

PermissionAllows
lookup:readGET /ip/{ip}, GET /ip/me, POST /check (IP only)
lookup:phonePOST /check with a phone number
lookup:batchPOST /ip/batch
email:checkPOST /email/check, GET /email/domain/{domain}, email in POST /check
email:batchPOST /email/batch
velocity:global"velocity_scope": "global" on POST /check
history:read, email:historyThe key's own lookup history (GET /lookups, GET /email/lookups)
Keep API keys on your servers. Never put them in browser JavaScript or mobile apps: anyone could read them there.

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"
200 OK: a Tor exit node
{
  "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"
200 OK: Hetzner IPv6 (abridged)
{
  "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"
422: when the caller's address is private (e.g. called from inside your LAN)
{
  "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"]}'
200 OK: one entry per input, in order (each result abridged)
{
  "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]"}'
200 OK: one combined score (abridged)
{
  "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]"}'
200 OK: disposable address (abridged: first 2 matches)
{
  "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"
}
200 OK: [email protected], a free provider (abridged)
{
  "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"]}'
200 OK: results in input order (each abridged)
{
  "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"
200 OK: an email alias/relay service (abridged)
{
  "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 signals has detected and a confidence (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-Id header; 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.

StatusCodesMeaning
400invalid_ip, invalid_phone, invalid_domain, invalid_json, invalid_request, empty_batchBad input
401authentication_requiredThis endpoint needs an API key
401invalid_credentialsUnknown, expired or revoked API key
403forbiddenThe key lacks the required permission
403source_ip_not_allowedThe caller is outside the key's source-IP allowlist
413batch_too_large, body_too_largeToo many items, or request body too large
415unsupported_media_typePOST without Content-Type: application/json
422non_public_addressPrivate, loopback, documentation or other special-purpose address (not risk-scored)
429rate_limitedRate limit reached; wait Retry-After seconds
400: GET /api/v1/ip/999.1.1.1
{
  "error": {
    "code": "invalid_ip",
    "message": "invalid IP address"
  }
}
422: GET /api/v1/ip/10.0.0.1
{
  "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"
    }
  }
}
401: POST /api/v1/email/check without a key
{
  "error": {
    "code": "authentication_required",
    "message": "email checks require an API key or a session"
  }
}
429: rate limit reached
{
  "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.

Headers of a normal response
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Ratelimit-Limit: 30
Ratelimit-Remaining: 29
Ratelimit-Reset: 31
X-Request-Id: 5ffa1c341c3712cc6a9dac15
Headers of a 429 response
HTTP/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: 83538938ea608fe8d7e82f91

On 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.