> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# IP Risk API

> Risk-score an IP address with geolocation, ISP, VPN/Tor, datacenter, threat, and claimed-country mismatch signals.

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, ISP and organization, VPN/Tor and datacenter flags, provider threat data, and `country_mismatch` when you send a claimed country.

## Request

```bash theme={null}
curl -X POST "https://verification.didit.me/v3/ip/risk/" \
  -H "x-api-key: <api_key>" \
  -H "Content-Type: application/json" \
  -d '{
    "ip_address": "8.8.8.8",
    "claimed_country": "ESP",
    "user_agent": "Mozilla/5.0",
    "vendor_data": "lead-123"
  }'
```

| Field             | Type   | Required | Description                                                           |
| ----------------- | ------ | -------- | --------------------------------------------------------------------- |
| `ip_address`      | string | Yes      | IPv4 or IPv6 address to score.                                        |
| `claimed_country` | string | No       | ISO 3166-1 alpha-2 or alpha-3 country claimed by the user or session. |
| `user_agent`      | string | No       | User agent observed by your backend.                                  |
| `vendor_data`     | string | No       | Your stable reference for this request.                               |
| `metadata`        | object | No       | Your non-sensitive request metadata.                                  |

## Response

```json theme={null}
{
  "request_id": "9a96ed2a-721e-4b86-8cbf-d61eda529279",
  "status": "In Review",
  "ip": {
    "ip_address": "8.8.8.8",
    "ip_country": "United States",
    "ip_country_code": "US",
    "ip_city": "Mountain View",
    "isp": "Google",
    "organization": "Google LLC",
    "is_vpn_or_tor": true,
    "is_data_center": false,
    "claimed_country": "ESP",
    "country_mismatch": true,
    "threat": { "is_proxy": true }
  },
  "vendor_data": "lead-123"
}
```

## 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_brand`, `device_model`, browser and OS versions, `user_agent`, `raw_device_data`, and cross-session matches.

A separate collector-plus-exchange device API would require a browser or native collector and is outside this endpoint.

## Billing and providers

IP Risk API calls use `ip_risk_api` pricing. It reuses Didit's existing IP enrichment path and cached network-address data where available.

Sandbox mode returns deterministic mock risk data and never spends managed provider credentials.