Skip to main content

​
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.
Didit Device and IP Analysis report screenshot with geolocation, device fingerprint and risk flags

​
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. 
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.

​
Schema

See Device & IP analysis in the Data Models reference for the canonical schema. 
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_sourceMeaningconfidencematch_mode
ip_addressShared IP — network co-location, never a device-identity claim.0.0co_occurrence
persistent_idExact stored persistent device identifier.1.0deterministic
legacy_fpLegacy didit-fp-* device-fingerprint hash.0.5probabilistic
recovered_highHigh-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 agreedeterministic 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.
ValueMeaning
Not FinishedThe IP analysis node has not completed for this session (default).
ApprovedNo warning fired, or every fired warning is configured to No action.
In ReviewAt least one fired warning is configured to Review (see warnings).
DeclinedA 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 RequestedA 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

{
  "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

{
  "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"
        }
      ]
    }
  ]
}