> ## 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.
# Device & IP analysis report
> Parse the Device & IP analysis report: geolocation, device fingerprint, VPN/Tor/proxy flags, document-vs-IP distance, and duplicate device matches.
## Overview
Device & IP analysis profiles every session by IP geolocation, device fingerprint, browser/OS, and network type. Geolocation and network-risk data are resolved through IP intelligence providers. It produces:
* An **IP geolocation** block (country, state, city, latitude/longitude, time zone) derived from the public IP.
* **Network-risk flags** — `is_vpn_or_tor` and `is_data_center` — to detect masking attempts (VPN, Tor exit nodes, hosting providers, anonymisers).
* **Cross-document distance calculations** — straight-line km between the IP location, the ID document's location, and the proof-of-address document's location.
* **Cross-session matches** — when the same IP address or device identity appears across sessions belonging to different users (grouped by `vendor_data`).
* **Device fingerprint recovery** — a high-confidence recovery signal that links sessions even after the user clears storage, switches incognito modes, or reinstalls the app.
## Where it appears in API responses
The decision endpoint returns Device & IP analysis as the plural array **`ip_analyses[]`** in `GET /v3/session/{sessionId}/decision/`. Entries are deduplicated `Location` observations keyed on (`node_id`, `ip_address`, `device_fingerprint`) — a single node can yield multiple entries when the user's IP or device changes mid-session.
```text theme={null}
GET /v3/session/{sessionId}/decision/
──▶ { "ip_analyses": [ { status, node_id, ip_address, ip, id_document, poa_document, warnings, matches, … }, … ] }
```
The shape below mirrors the canonical schema — see [Data models](/reference/data-models#ip-analysis).
## Schema
See [Device & IP analysis in the Data Models reference](/reference/data-models#ip-analysis) for the canonical schema.
```typescript theme={null}
interface IPAnalysisV3 {
status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review' | 'Resub Requested';
node_id: string | null;
// Device
device_brand: string | null;
device_model: string | null;
browser_family: string | null;
os_family: string | null;
platform: 'mobile' | 'tablet' | 'desktop' | null;
device_fingerprint: string | null;
// IP geolocation
ip_country: string | null;
ip_country_code: string | null; // ISO 3166-1 alpha-2
ip_state: string | null;
ip_city: string | null;
latitude: number | null;
longitude: number | null;
ip_address: string;
isp: string | null;
organization: string | null;
is_vpn_or_tor: boolean;
is_data_center: boolean;
time_zone: string | null;
time_zone_offset: string | null;
// Distance blocks — each carries its own location + distances to the other two
ip: {
location: { latitude: number; longitude: number } | null;
distance_from_id_document: number | null; // km
distance_from_poa_document: number | null; // km
};
id_document: {
location: { latitude: number; longitude: number } | null;
distance_from_ip: number | null;
distance_from_poa_document: number | null;
};
poa_document: {
location: { latitude: number; longitude: number } | null;
distance_from_ip: number | null;
distance_from_id_document: number | null;
};
warnings: Warning[]; // see Data Models — Warning object
// Cross-session matches — up to 5 IP matches + 5 device matches
matches: IPAnalysisMatch[];
}
interface IPAnalysisMatch {
session_id: string; // matching session UUID
session_number: number;
vendor_data: string | null;
verification_date: string | null; // "YYYY-MM-DDTHH:MM:SSZ"
match_type: 'ip_address' | 'device_fingerprint';
match_source: 'ip_address' | 'persistent_id' | 'legacy_fp' | 'recovered_high';
matched_value: string | null; // shared IP, device identifier, or recovered device UUID
status: string; // lifecycle status of the matching session
is_blocklisted: boolean; // currently always false
api_service: string | null; // standalone API service; null for workflow sessions
source: 'session';
device_info: {
device_brand: string | null;
device_model: string | null;
browser_family: string | null;
os_family: string | null;
platform: string | null;
device_fingerprint: string | null;
};
location_info: {
ip_address: string | null;
ip_country: string | null;
ip_country_code: string | null;
ip_state: string | null;
ip_city: string | null;
is_vpn_or_tor: boolean;
is_data_center: boolean;
};
confidence: number; // 0–1, = 1 - P(false positive)
match_mode: 'deterministic' | 'probabilistic' | 'co_occurrence';
// Present only when match_source = 'recovered_high'
recovery_similarity?: number; // cosine similarity, 4 decimals
tls_ja4_corroborated?: boolean; // TLS JA4 fingerprints of both observations agree
recovery_gate_reason?: string; // e.g. 'hardware_root_match'
}
```
### Match semantics
`match_source` tells you how the match was reached, and `confidence` scores how likely it is to be *wrong* (`confidence = 1 - P(false positive)`):
| `match_source` | Meaning | `confidence` | `match_mode` |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------- |
| `ip_address` | Shared IP — network co-location, never a device-identity claim. | `0.0` | `co_occurrence` |
| `persistent_id` | Exact stored persistent device identifier. | `1.0` | `deterministic` |
| `legacy_fp` | Legacy `didit-fp-*` device-fingerprint hash. | `0.5` | `probabilistic` |
| `recovered_high` | High-confidence fuzzy fingerprint-recovery hit after strict hard gates. | `1.0` when hardware-rooted, otherwise `< 1.0`, boosted when TLS JA4 and IP country independently agree | `deterministic` or `probabilistic` |
Lower-confidence recovery candidates surface as risk warnings only — never in `matches[]`. IP matches and device matches are capped at 5 each, so the array holds at most 10 entries.
## Status values
Statuses are feature-level `FeatureStatusChoices` values. Each fired warning maps to the action configured for it on the workflow node; the strongest action wins.
| Value | Meaning |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | The IP analysis node has not completed for this session (default). |
| `Approved` | No warning fired, or every fired warning is configured to No action. |
| `In Review` | At least one fired warning is configured to Review (see [warnings](/core-technology/ip-analysis/warnings-ip-analysis)). |
| `Declined` | A blocklist warning fired (`IP_ADDRESS_IN_BLOCKLIST` or `DEVICE_FINGERPRINT_IN_BLOCKLIST` — always decline), or a configurable warning is set to Decline for your workflow. |
| `Resub Requested` | A reviewer requested resubmission of this step. |
Custom status rules configured on the IP analysis node can further adjust the resulting status.
## VPN, proxy, and Tor detection
`is_vpn_or_tor` and `is_data_center` are independent boolean flags returned for every session. When `is_vpn_or_tor` is `true`, Didit also emits the `PRIVATE_NETWORK_DETECTED` warning so your team can act on it via workflow configuration. Datacenter-only traffic (without VPN/Tor) sets `is_data_center=true` but does not auto-warn — use this as an additional signal in your own scoring.
## Examples
### Approved
```json theme={null}
{
"ip_analyses": [
{
"status": "Approved",
"node_id": "ip-1",
"device_brand": "Apple",
"device_model": "iPhone",
"browser_family": "Mobile Safari",
"os_family": "iOS",
"platform": "mobile",
"device_fingerprint": "didit-fp-8d2c7a91f4b3e042",
"ip_country": "Spain",
"ip_country_code": "ES",
"ip_state": "Barcelona",
"ip_city": "Barcelona",
"latitude": 41.4022,
"longitude": 2.1407,
"ip_address": "83.50.226.71",
"isp": "Telefonica",
"organization": "Telefonica de Espana",
"is_vpn_or_tor": false,
"is_data_center": false,
"time_zone": "Europe/Madrid",
"time_zone_offset": "+0100",
"ip": {
"location": { "latitude": 41.4022, "longitude": 2.1407 },
"distance_from_id_document": 23.4,
"distance_from_poa_document": 12.3
},
"id_document": {
"location": { "latitude": 41.2706, "longitude": 1.9770 },
"distance_from_ip": 23.4,
"distance_from_poa_document": 18.7
},
"poa_document": {
"location": { "latitude": 41.3128, "longitude": 2.0540 },
"distance_from_ip": 12.3,
"distance_from_id_document": 18.7
},
"warnings": [],
"matches": []
}
]
}
```
### Declined — IP blocklist hit + VPN + duplicate device
```json theme={null}
{
"ip_analyses": [
{
"status": "Declined",
"node_id": "ip-1",
"device_brand": null,
"device_model": null,
"browser_family": "Chrome",
"os_family": "Linux",
"platform": "desktop",
"device_fingerprint": "didit-fp-a13c0d22e8b94471",
"ip_country": "Netherlands",
"ip_country_code": "NL",
"ip_state": "North Holland",
"ip_city": "Amsterdam",
"latitude": 52.3676,
"longitude": 4.9041,
"ip_address": "45.61.20.5",
"isp": "Example Hosting",
"organization": "Example Hosting BV",
"is_vpn_or_tor": true,
"is_data_center": true,
"time_zone": "Europe/Amsterdam",
"time_zone_offset": "+0100",
"ip": {
"location": { "latitude": 52.3676, "longitude": 4.9041 },
"distance_from_id_document": 1834.2,
"distance_from_poa_document": 1822.5
},
"id_document": {
"location": { "latitude": 40.4168, "longitude": -3.7038 },
"distance_from_ip": 1834.2,
"distance_from_poa_document": 14.0
},
"poa_document": {
"location": { "latitude": 40.5070, "longitude": -3.6720 },
"distance_from_ip": 1822.5,
"distance_from_id_document": 14.0
},
"warnings": [
{
"feature": "LOCATION",
"risk": "IP_ADDRESS_IN_BLOCKLIST",
"additional_data": { "ip_address": "45.61.20.5" },
"log_type": "error",
"short_description": "IP address in blocklist",
"long_description": "The IP address used for this session was found in the application's IP blocklist, indicating a known suspicious or forbidden origin.",
"node_id": "ip-1"
},
{
"feature": "LOCATION",
"risk": "PRIVATE_NETWORK_DETECTED",
"additional_data": null,
"log_type": "warning",
"short_description": "Private network (VPN/Tor) detected",
"long_description": "The system detected that the user tried to use a private network (VPN/TOR) to complete the verification process.",
"node_id": "ip-1"
},
{
"feature": "LOCATION",
"risk": "COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP",
"additional_data": { "document_country_code": "ESP", "ip_country_code": "NLD" },
"log_type": "warning",
"short_description": "Document country does not match IP country",
"long_description": "The country from the document does not match the country from the IP address, suggesting a potential mismatch between the document and the user's location.",
"node_id": "ip-1"
},
{
"feature": "LOCATION",
"risk": "DUPLICATED_DEVICE_FINGERPRINT",
"additional_data": {
"duplicated_session_id": "11111111-2222-3333-4444-555555555555",
"duplicated_session_number": 1042,
"api_service": null,
"match_source": "persistent_id"
},
"log_type": "warning",
"short_description": "Duplicated device fingerprint from another session",
"long_description": "The same device fingerprint was detected in another session with a different vendor_data, which may indicate multiple identities verified from the same device.",
"node_id": "ip-1"
}
],
"matches": [
{
"session_id": "11111111-2222-3333-4444-555555555555",
"session_number": 1042,
"vendor_data": "user-other",
"verification_date": "2026-05-28T14:03:21Z",
"match_type": "device_fingerprint",
"match_source": "persistent_id",
"matched_value": "pid_9f1c2b7a8d3e4f50",
"status": "Declined",
"is_blocklisted": false,
"api_service": null,
"source": "session",
"device_info": {
"device_brand": null,
"device_model": null,
"browser_family": "Chrome",
"os_family": "Linux",
"platform": "desktop",
"device_fingerprint": "didit-fp-a13c0d22e8b94471"
},
"location_info": {
"ip_address": "45.61.23.99",
"ip_country": "Netherlands",
"ip_country_code": "NL",
"ip_state": "North Holland",
"ip_city": "Amsterdam",
"is_vpn_or_tor": true,
"is_data_center": true
},
"confidence": 1.0,
"match_mode": "deterministic"
}
]
}
]
}
```
## Related
* [Device & IP analysis warnings](/core-technology/ip-analysis/warnings-ip-analysis) — every warning code IP analysis can emit
* [Device & IP analysis overview](/core-technology/ip-analysis/overview) — what each block measures
* [Data models — IP analysis](/reference/data-models#ip-analysis) — canonical schema
* [Webhooks](/integration/webhooks) — `status.updated` carries the same IP analysis payload