VerifIP IP reputation API reference 

Every endpoint takes Authorization: Bearer YOUR_API_KEY (your VerifIP API key (under API Keys → VerifIP)). Batch endpoints take 1–100 items and are for paid plans only. Every endpoint and field is in the OpenAPI spec; GET /health needs no key.

VerifIP endpoints and methods

Example request for each endpoint

GET /v1/check?ip=185.220.101.1   (illustrative; live values change)

{
  "ip": "185.220.101.1", "ip_version": 4,
  "fraud_score": 43, "verdict": "challenge", "threat_confidence": "low",
  "threat_categories": ["tor", "proxy", "attacker"],
  "is_tor": true, "is_proxy": true, "is_datacenter": true,
  "blocklist_count": 3, "country_code": "DE", "asn": 60729,
  "signal_breakdown": { "tor_exit": 25, "proxy_detected": 15, "datacenter_ip": 10,
    "blocklist_consensus": 12, "known_attacker": 15, "firehol_l2": 15 }
}

POST /v1/check/batch
{"ips":["1.1.1.1","8.8.8.8","not-an-ip"]}

{
  "results": [
    { "ip": "1.1.1.1", "fraud_score": 0, "verdict": "allow", ... },
    { "ip": "8.8.8.8", "fraud_score": 0, "verdict": "allow", ... },
    { "ip": "not-an-ip", "fraud_score": 0, "invalid": true, "error": "..." }
  ]
}

GET /v1/email?email=user@mailinator.com

{
  "email": "user@mailinator.com", "risk_score": 35,
  "valid_syntax": true, "mx_found": true, "is_disposable": true,
  "is_free_provider": false, "is_role_based": false,
  "domain": "mailinator.com", "domain_age_days": 8494,
  "signal_breakdown": { "disposable_domain": 35 }
}

POST /v1/email/batch
{"emails":["a@gmail.com","b@mailinator.com"]}

{ "results": [ { "email": "a@gmail.com", "risk_score": 5, ... }, ... ] }

GET /v1/phone?phone=%2B917006636358

{
  "phone": "+917006636358", "risk_score": 0, "valid": true,
  "country_code": "IN", "carrier": "", "line_type": "mobile",
  "is_voip": false, "signal_breakdown": {}
}

POST /v1/phone/batch
{"phones":["+14155552671","+447911123456"]}

{ "results": [ { "phone": "+14155552671", "valid": true, ... }, ... ] }

GET /v1/url?url=https%3A%2F%2Fexample.com%2Flogin

{
  "url": "https://example.com/login", "risk_score": 0,
  "is_phishing": false, "is_malware": false, "in_phishtank": false,
  "spamhaus_dbl": false, "domain_age_days": 11374,
  "ssl_valid": true, "ssl_status": "valid", "signal_breakdown": {}
}

A listed URL looks like this (illustrative):
{ "risk_score": 50, "is_phishing": true, "in_phishtank": true,
  "domain_age_days": 3, "signal_breakdown": { "phishtank": 35, "new_domain": 15 } }

POST /v1/url/batch
{"urls":["https://example.com","https://example.org/login"]}

{ "results": [ { "url": "https://example.com", "risk_score": 0, ... }, ... ] }

GET /v1/whois?ip=34.87.12.111

{
  "ip": "34.87.12.111", "ip_version": 4, "network_cidr": "34.80.0.0/12",
  "network_handle": "NET-34-64-0-0-1", "network_name": "GOOGLE-CLOUD", "org_name": "Google LLC",
  "abuse_contact": "network-abuse@google.com", "rir": "ARIN",
  "allocation_date": "2018-04-09", "country_code": "US",
  "asn": 396982, "asn_org": "Google LLC"
}

GET /v1/assess?ip=34.87.12.111&email=user@gmail.com

{
  "overall_risk": 10,
  "ip": { "fraud_score": 10, "verdict": "allow", "threat_confidence": "none", ... },
  "email": { "risk_score": 5, "is_free_provider": true, ... }
}

POST /v1/report
{"ip":"185.220.101.1","is_fraud":true,"category":"spam","comment":"Bulk spam"}

{ "request_id": "…", "status": "accepted", "message": "Fraud report submitted successfully." }

What fields does /v1/check return?

Verdict, freshness and completeness

Email answer · /v1/email

Phone answer · /v1/phone

URL answer · /v1/url

WHOIS answer · /v1/whois

Assess answer · /v1/assess

Report body and answer · /v1/report

Batch response format

Health · GET /health

Signal breakdown · weights

Only signals that fired appear in signal_breakdown. Correlated signals are combined, so the score is not their sum. Sources are listed on Data sources.

How should I read the fraud score?

How do batch requests work?

1–100 items, paid plans only (403 plan_required on Free, not billed). Each item must be a string of at most 64 characters (IPs, phones), 320 (emails) or 2,048 (URLs); otherwise the whole request is a 400. A batch is one unit of your burst rate, and it reserves its full length from your quota up front (refused whole with 429 if it does not fit); only answered entries are billed. Results come back in input order. Entries without an answer are marked — never read their zeros as clean. If every entry is invalid the batch is a 400; if no entry could be answered (invalid ones aside) it is a 503; neither is billed. IP batches use local data only (no reverse DNS, no external reputation lookup). Email and URL batches do full lookups for about 15 uncached unique domains, marking the rest external_lookups, and stop waiting on lookups 2 seconds after the batch starts, marking what was still running batch_deadline. Neither is billed; resubmit those entries.

Does VerifIP support IPv6?

/v1/check, /v1/check/batch, /v1/whois, /v1/assess (its ip) and /v1/report accept IPv6. IPv6 answers set ip_version: 6 and list in signals_unavailable the sources that have no IPv6 data, so the score is built from fewer lists. blocklist_count is always 0 for IPv6. Link-local, unique-local (fc00::/7), multicast, loopback, unspecified and documentation (2001:db8::/32, 3fff::/20) addresses are refused with 400 invalid_ip; an IPv4-mapped address (::ffff:a.b.c.d) is answered as the IPv4 it carries.

Which response headers does VerifIP send?

When to retry

Wait the Retry-After header (every 429 and capacity_unavailable); since API 1.4.2 the body repeats it as retry_after. A retry is a new request: it is billed like one.

What are the rate limits on each plan?

The Free plan is also capped at 1,000 requests/day (reset 00:00 UTC) so the monthly quota can't be used up in a single day. Paid plans have no daily cap — only the monthly quota applies (reset 00:00 UTC on the 1st). Requests beyond the quota are refused with HTTP 429 rate_limit_exceeded, which is not billed, until the window resets or you upgrade. A batch reserves its full length up front, so a batch that does not fit in what is left is refused whole (429, not billed). One /v1/assess call is 1 unit, however many entities it checks.

Every metered response carries X-RateLimit-Burst-Limit and X-RateLimit-Burst-Period. Burst rates are a soft brake, not an exact limit: they are enforced per Cloudflare location and per machine, with counts shared after a short delay, so traffic spread over several connections can briefly exceed them, while a single connection is held close to the figure. The monthly quota is exact and is the commercial limit. Pace with your own client-side limiter and honour Retry-After rather than relying on 429s to slow you down. Independently, the edge blocks a single source IP above about 350 requests per 10 seconds. A batch is one burst unit whatever its length. Each key is also held to about 3,000 requests per 60 seconds (429 burst_limit_exceeded, Retry-After 60) against runaway loops and leaked keys. At very high load, free-plan requests may be refused 503 capacity_unavailable until 00:00 UTC, and paid keys may drop to a fair-share burst limit; neither is billed. A request body that is not valid JSON is a 400 invalid_request, not billed.

Errors are JSON: { "error": "<code>", "message": "<text>" }. Wait the Retry-After header (every 429 and capacity_unavailable); since API 1.4.2 the body repeats it as retry_after. A degraded 503 has no error field: it carries the partial answer with degraded: true. Every 503 sets X-VerifIP-Degraded: true, so branch on the HTTP status and the error code first, and treat the header as a monitoring signal. Every response carries X-Request-ID; quote it to support.

This product includes GeoLite Data created by MaxMind, available from https://www.maxmind.com. IP blocklist data: The Spamhaus Project (DROP). Phishing data: PhishTank, CC BY-SA 2.5. Malware data: abuse.ch. Hextner uses the IP2Proxy LITE database for IP geolocation. Full notices: Data sources.