IP checks¶

The overview describes the common field interpretation rules, failure reasons, and full/light file formats.

Parent: ip_check_results[]. All stored IP check results for the session. The item count is not the number of user attempts: there may be multiple addresses and processing results.

Fields of an ip_check_results[] item.

Fields marked “Required” are always present within this object. Other fields are included when a value is available; null is excluded from the response.

Field	JSON type	Purpose and conditions
`result`	boolean	Required. Whether the check was accepted according to the settings. May be `true` when a provider error is allowed; does not guarantee that all network data was retrieved.
`verdict`	string, enum	Required: `ok` — accepted; `suspicious` — suspicious / insufficient data when rejected; `blocked` — blocked based on the data found. Additional country checks may set `result` to `false` without changing `verdict`; consider both fields.
`ip`	string	Checked IPv4/IPv6 address.
`network_asn`	string	Autonomous system number in the source's format.
`network_range`	string	Network range in the source's format.
`network_provider`	string	Network provider.
`network_organisation`	string	Organization that owns the network.
`network_type`	string, enum	`residential` — home network; `business` — corporate network; `wireless` — wireless network; `hosting` — hosting; `unknown` — unknown.
`continent_name`	string	Continent name based on the IP address.
`continent_code`	string	Continent code based on the IP address.
`country_name`	string	Country name based on the IP address.
`country_code`	string	Country code based on the IP address.
`city_name`	string	City name based on the IP address.
`device_estimate_address`	integer	Estimated number of devices at the IP address, a non-negative number; when the source provides an estimate.
`device_estimate_subnet`	integer	Estimated number of devices in the subnet, a non-negative number.
`is_proxy`	boolean	Proxy indicator.
`is_vpn`	boolean	VPN indicator.
`is_tor`	boolean	Tor indicator.
`is_hosting`	boolean	Hosting / data center indicator.
`is_compromised`	boolean	Compromise indicator according to the source's classification.
`is_scraper`	boolean	Automated data collection indicator according to the source's classification.
`is_anonymous`	boolean	Anonymization indicator according to the source's classification.
`risk_score`	integer	Risk score; compared against the configured threshold. Some allowed errors store `0`. This API defines no universal scale or upper bound.
`confidence`	integer	Provider's confidence in the assessment; units and upper bound are not defined.
`failure_reason`	object	Failure reason, if recorded; see the structure.

Rejection depends, among other things, on settings for VPN/proxy and data center rejection, the risk threshold, country mismatch, and error handling. A network indicator set to false differs from an absent indicator.

JSON examples¶

Fragments of the root response object, not complete responses. All values and URLs are illustrative. File formats follow the explanations on this page.

{
  "ip_check_results": [
    {
      "ip": "192.0.2.10",
      "result": true,
      "verdict": "ok",
      "is_proxy": false,
      "is_vpn": false,
      "is_tor": false,
      "risk_score": 0
    }
  ]
}