Skip to main content

​
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 flags. is_vpn is also true for a company VPN appliance, which sets is_corporate_vpn; the sample lets those users through. Test any rule on your own traffic before you enforce it.
Suspected VPN labels never set the booleans. classification can return the corroboration-only labels suspected_vpn and its legacy spelling vpn_suspect (same meaning, written by an older ingestion path) for IPs where traffic patterns resemble VPN behavior but we lack confirmed protocol evidence. By design they return is_vpn: false and set no other boolean. suspected_proxy is different: it sets is_proxy: true, so a rule on is_proxy blocks it. If your integration reads only the top-level classification, treat suspected_vpn / vpn_suspect as advisory: gate on the booleans (or on by_primary_category semantics) for block/allow decisions, and on Pro and up use confidence to tune how much weight a suspect label gets (it is null on Intro and Starter). For reference, is_vpn: true corresponds exactly to classification in vpn, commercial_vpn, corporate_vpn, vpn_concentrator (retired 2026-10; no longer assigned), or vpn_hosting — confirmed VPN endpoints only; tor and relay have their own dedicated booleans.

​
Residential proxy hits

On every plan, a residential proxy hit’s risk_score follows how recently we saw the address, in the freshness_class buckets (the bucket itself is shown from Pro): current 95–100, recent 75–85, stale 45–60, frozen 25–35. Within a bucket, an address seen on more days and through more networks scores higher. A VPN, proxy, threat-list or hosting match on the same address keeps the score it would have on its own, so the bucket never lowers it. On a mobile carrier, a satellite network or a secure web gateway, many people share one address, so a proxy sighting there says little about the person in front of you. A residential proxy hit on one of these networks that we list scores at most 60, however recent, and carries the SHARED_ADDRESS_NETWORK reason, with the kind of network in detail.network_type. The list does not yet cover every such network, so the reason, not the network’s type, tells you the cap applied. Step those hits up, with a challenge or a review, rather than block them: the sample above blocks every residential proxy hit, so a rule that blocks only above 60 and steps up the rest follows this advice.

​
Batch

For lists of IPs (Starter tier and above), batch endpoint cuts latency dramatically:
Up to 100 IPs per request. results holds one row per distinct IP string, in the order each first appears. An exact repeat is looked up once, so send each IP in canonical form and match rows to your inputs by ip, not by position. A row is either a lookup result with the same fields as the single-IP endpoint, or {"ip": ..., "error": ...} for an IP that could not be looked up; see the batch endpoint reference.

​
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 you need per-IP lookups at that scale, use the MMDB download: local lookups with no rate limits. The files regenerate once a day, so pull them daily via cron. The API itself refreshes daily too, so a daily mirror stays within about a day of what the API returns.

​
What to do with unknown

classification: "unknown" means we hold no 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).

​
Report a result you think is wrong

If you think a lookup got an address wrong, email service.desk@whoisxmlapi.com. The link starts the email for you. These help us look into it:
  • The IP address.
  • When you looked it up, in UTC.
  • What we returned: paste the response, or at least classification, the is_* flags and risk_score.
  • What you expected, and why: for example, that the address is your own office’s.
Leave your API key out of the email.