Single IP
The most common pattern: classify one IP at a time.
is_vpn, is_proxy, is_residential_proxy, is_tor, is_hosting,
is_cdn, is_relay are the boolean fields most fraud pipelines use.
Suspected labels never set the booleans. classification can return
corroboration-only labels — suspected_vpn, its legacy spelling
vpn_suspect (same meaning, written by an older ingestion path), and
suspected_proxy — for IPs where traffic patterns resemble VPN/proxy
behavior but we lack confirmed protocol evidence. By design,
suspected_vpn / vpn_suspect return is_vpn: false (and set no other
boolean). If your integration reads only the top-level classification,
treat any suspected_* / *_suspect value as advisory — gate on the
booleans (or on by_primary_category semantics) for block/allow
decisions, and use confidence to tune how much weight a suspect label
gets. For reference, is_vpn: true corresponds exactly to
classification in vpn, commercial_vpn, corporate_vpn,
vpn_concentrator, or vpn_hosting — confirmed VPN endpoints only;
tor and relay have their own dedicated booleans.
Batch
For lists of IPs (Starter tier and above), batch endpoint cuts latency
dramatically:
Up to 100 IPs per request. Each result has the same shape as the single-IP
endpoint. Order matches input.
High-volume
If you’re checking >1 M IPs/day, don’t use the API one-at-a-time —
use the bulk export for nightly mirroring and
hit local storage.
If real-time is required at scale, use the MMDB download:
sub-millisecond local lookups with no rate limits, refreshed hourly on
your side via cron. The trade-off is lag (your mirror is at most an
hour stale).
What to do with unknown
classification: "unknown" means we have no high-confidence label for
this IP. Don’t treat unknown as either clean or suspicious — treat it as
“no data.” Common in:
- Brand new ranges (recently allocated by a RIR)
- Sparse cellular ranges with infrequent observations
- Ranges deliberately excluded from our scanning (per opt-out requests)
Most production callers fall through unknown to their next signal
(behavioral, device, payment risk).
