Skip to main content
POST
Check an IP address
Scores one address and returns a single verdict alongside each source’s own reading. The verdict follows a fixed rule — it is never an average of the scores, because the sources use incompatible scales. Billable. Send an Idempotency-Key so a retry replays the original answer instead of paying twice. Every proxy order you have been delivered grants one free check, and a repeat of a recent check on the same address is free for everyone. Use Get check quota to see what is left before you call.
This endpoint is behind the ip_reputation.check.enabled feature flag. Read GET /flags to find out whether it is available to you; a disabled feature answers 403.

Request

string
required
The IPv4 or IPv6 address to check. Must be publicly routable — private and reserved ranges have no reputation to report and are rejected with 422. IPv6 is canonicalised, so the ip in the response may differ from what you sent; treat the returned value as the address that was checked.
string
A UUID you generate per submission and reuse on retry. Reusing a key with a different address answers 409.

Response

string
clean, suspicious, risky or blacklisted.
integer
0–100. The highest score any source gave, not the mean.
object
amount (decimal string — parse it, do not assume a number), currency (always USD) and free. free: true with cached: true means a recent result was reused; free: true with cached: false means one of your free checks was spent.
object
tor, vpn, proxy_detected, datacenter, recent_abuse, known_abuser and blocklists. proxy_detected and datacenter are reported for information only and never move the verdict — a bare address carries no statement of what it is meant to be.
object[]
One entry per source: vendor, label, status (ok or unavailable), and — when it answered — band (clean, suspicious, high_risk), score and risk. A source that could not be reached is excluded from the verdict rather than counted as clean, so never read a missing band as a good sign.Each entry also carries score_metric, risk_metric and score_derived, which say what that source’s two values actually are. Read them before putting two sources side by side: score is a measurement for some sources and a band midpoint for others, and risk is not the same question from one source to the next — one reports a risk level, another how frequently the address is reported. A high score beside a low wording is those two fields disagreeing about the question, not the source contradicting itself.
boolean
True when at least one source could not be reached, so the verdict rests on fewer opinions than usual.
boolean
True when a recent result for this exact address was reused. Cached answers are free and are not stored in your history.
string | null
Identifies the stored result for Get a check. null for a cached answer, which stores nothing.

Errors

Example