Skip to main content
POST
curl
Use POST /v3/ip/risk/ when your backend already has an IP address and needs a server-to-server risk decision. The response includes geolocation, network ownership, VPN/Tor and data-center flags, threat data, and country_mismatch when you send a claimed country.

Interpret the response

  • status is In Review when the resolved country conflicts with claimed_country, or when the address is associated with VPN, Tor, or data-center infrastructure. Otherwise it is Approved.
  • ip.ip_country_code contains the resolved country code. Compare countries through ip.country_mismatch instead of comparing raw country strings yourself.
  • ip.latitude and ip.longitude are approximate network geolocation, not a precise device location.
  • ip.is_vpn_or_tor, ip.is_data_center, ip.proxy_type, and ip.threat carry network-risk evidence.
  • ip.asn_number, ip.asn_organization, ip.connection_type, and ip.carrier describe the network the address belongs to.
  • request_id is the API session id. Store it with vendor_data if you need to correlate the result with later webhooks or console activity.
IP enrichment is best effort. If no enrichment source returns usable data, the endpoint returns an approved response with ip.ip_address: null, ip.country_mismatch: null, and an empty ip.threat object. Individual enrichment fields can also be null when unavailable.

Device intelligence

The IP Risk API is a pure server-to-server endpoint. Device fingerprinting is not, because a backend cannot observe browser or device signals by itself. For hosted-flow and SDK sessions, Didit exposes the already collected device fields on the session response, including device_fingerprint, device and browser details, user_agent, raw device data, and cross-session matches.

Sandbox behavior

Sandbox keys validate the request and return deterministic approved data. They do not contact external intelligence services, consume credits, create a session, or contribute to Networks.

Billing

IP Risk API calls use IP Risk API pricing. A live request is billable once the lookup starts.

Authorizations

x-api-key
string
header
required

Body

application/json
ip_address
string<ip>
required

IPv4 or IPv6 address to score.

Example:

"8.8.8.8"

claimed_country
string

Optional ISO 3166-1 alpha-2 or alpha-3 country claimed by the user or session. Used to calculate country_mismatch.

Maximum string length: 3
Example:

"ESP"

user_agent
string

User agent observed by your backend. Stored as request context; it does not provide device fingerprinting.

Maximum string length: 512
vendor_data
string

Your stable reference for this request. Stored on the API session and echoed in the response.

metadata
object | null

Your non-sensitive JSON metadata. Stored on the API session and echoed in the response.

Response

The risk evaluation completed. Inspect status for the decision; HTTP is always 200 for completed lookups.

request_id
string<uuid>
required

Id of the API session created for this request. Store it with vendor_data if you need to correlate the result with later webhooks or console activity.

status
enum<string>
required

Decision for this API session: In Review on network or country-mismatch risk, otherwise Approved.

Available options:
Approved,
In Review
created_at
string<date-time>
required

Timestamp of this response.

vendor_data
string | null

Echo of the vendor_data you sent, null when you did not send one.

metadata
object | null

Echo of the metadata you sent, null when you did not send one.

ip
object

IP risk result. Individual enrichment fields can be null when the lookup returned no usable data.