Geräte- und IP-Analyse-Bericht: Felder & Treffer

Übersicht

Die Geräte- und IP-Analyse profiliert jede Sitzung anhand von IP-Geolokalisierung, Geräte-Fingerprint, Browser/Betriebssystem und Netzwerktyp. Geolokalisierung, Anreicherung um Netzwerkrisiken, Geräteabgleich und Integritätsprüfungen von Remote-Geräten laufen asynchron ab, während der Benutzer die Verifizierung durchführt. Geräte- und IP-Beobachtungen bleiben verfügbar, während die Analyse noch aussteht; Geolokalisierungsfelder können leer sein, bis die Ergebnisse eintreffen oder wenn die Adresse nicht öffentlich ist. Wenn Ihr Workflow diese Prüfungen nutzt, um das Ergebnis zu bestimmen oder einen nachfolgenden Schritt auszuwählen, bleibt die Sitzung im Status In Progress, bis die erforderlichen Ergebnisse vorliegen. Wenn eine erforderliche Analyse nach begrenzten Wiederholungsversuchen weiterhin nicht verfügbar ist, wechselt die Sitzung für eine manuelle Entscheidung zu In Review. Fehler bei optionalen Anreicherungen verhindern den Abschluss nicht, und manuelle Entscheidungen bleiben maßgeblich. Sie liefert:

Einen IP-Geolokalisierungs-Block (Land, Bundesland/Region, Stadt, Breitengrad/Längengrad, Zeitzone), der aus der öffentlichen IP abgeleitet wird.
Netzwerk-Risiko-Flags — is_vpn_or_tor und is_data_center —, um Verschleierungsversuche zu erkennen (VPN, Tor-Exit-Nodes, Hosting-Provider, Anonymisierungsdienste).
Dokumentübergreifende Distanzberechnungen — Luftlinie in km zwischen dem IP-Standort, dem Standort des Ausweisdokuments und dem Standort des Adressnachweis-Dokuments.
Sitzungsübergreifende Übereinstimmungen — wenn dieselbe IP-Adresse oder Geräteidentität über Sitzungen verschiedener Benutzer hinweg auftritt (gruppiert nach vendor_data).
Geräte-Fingerprint-Wiederherstellung — ein Wiederherstellungssignal mit hohem Konfidenzwert, das Sitzungen selbst dann verknüpft, wenn der Benutzer den Speicher leert, in den Inkognito-Modus wechselt oder die App neu installiert.

Screenshot des Berichts zur Didit Geräte- und IP-Analyse mit Geolokalisierung, Geräte-Fingerprint und Risiko-Flags

Wo es in API-Antworten erscheint

Der Decision-Endpoint gibt die Geräte- und IP-Analyse als Array ip_analyses[] in GET /v3/session/{sessionId}/decision/ zurück. Die Einträge sind deduplizierte Location-Beobachtungen mit dem Schlüssel (node_id, ip_address, device_fingerprint) — ein einzelner Knoten kann mehrere Einträge liefern, wenn sich die IP-Adresse oder das Gerät des Benutzers während der Sitzung ändert.

GET /v3/session/{sessionId}/decision/
  ──▶ { "ip_analyses": [ { status, node_id, ip_address, ip, id_document, poa_document, warnings, matches, … }, … ] }

Die folgende Struktur spiegelt das kanonische Schema wider — siehe Datenmodelle.

Schema

Siehe Geräte- und IP-Analyse in der Datenmodell-Referenz für das kanonische 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-Semantik

match_source gibt an, wie die Übereinstimmung ermittelt wurde, und confidence bewertet, wie wahrscheinlich es ist, dass sie falsch ist (confidence = 1 - P(false positive)):

`match_source`	Bedeutung	`confidence`	`match_mode`
`ip_address`	Geteilte IP — Netzwerk-Co-Location, niemals ein Beleg für Geräteidentität.	`0.0`	`co_occurrence`
`persistent_id`	Exakte gespeicherte persistente Gerätekennung.	`1.0`	`deterministic`
`legacy_fp`	Veralteter `didit-fp-*`-Geräte-Fingerprint-Hash.	`0.5`	`probabilistic`
`recovered_high`	Treffer durch unscharfe Fingerabdruck-Wiederherstellung mit hohem Konfidenzwert nach strikten Ausschlusskriterien.	`1.0` bei hardwarebasierter Bindung, sonst `< 1.0`, erhöht, wenn TLS JA4 und IP-Land unabhängig voneinander übereinstimmen	`deterministic` oder `probabilistic`

Wiederherstellungskandidaten mit niedrigerem Konfidenzwert werden ausschließlich als Risikowarnungen ausgegeben — niemals in matches[]. IP-Matches und Geräte-Matches sind jeweils auf 5 begrenzt, sodass das Array maximal 10 Einträge enthält.

Statuswerte

Statuswerte sind FeatureStatusChoices-Werte auf Funktionsebene. Jede ausgelöste Warnung wird der Aktion zugeordnet, die auf dem Workflow-Knoten für sie konfiguriert ist; die stärkste Aktion setzt sich durch.

Wert	Bedeutung
`Not Finished`	Der Knoten für die IP-Analyse wurde für diese Sitzung noch nicht abgeschlossen (Standard).
`Approved`	Es wurde keine Warnung ausgelöst oder jede ausgelöste Warnung ist auf Keine Aktion konfiguriert.
`In Review`	Mindestens eine ausgelöste Warnung ist auf Prüfung konfiguriert (siehe Warnungen).
`Declined`	Eine Sperrlisten-Warnung wurde ausgelöst (`IP_ADDRESS_IN_BLOCKLIST` oder `DEVICE_FINGERPRINT_IN_BLOCKLIST` — führt immer zur Ablehnung), oder eine konfigurierbare Warnung ist für Ihren Workflow auf Ablehnen gesetzt.
`Resub Requested`	Ein Prüfer hat die erneute Einreichung dieses Schritts angefordert.

Benutzerdefinierte Statusregeln, die auf dem IP-Analyse-Knoten konfiguriert sind, können den resultierenden Status weiter anpassen.

VPN-, Proxy- und Tor-Erkennung

is_vpn_or_tor und is_data_center sind unabhängige boolesche Flags, die für jede Sitzung zurückgegeben werden. Wenn is_vpn_or_tor auf true steht, gibt Didit zusätzlich die Warnung PRIVATE_NETWORK_DETECTED aus, damit Ihr Team per Workflow-Konfiguration darauf reagieren kann. Reiner Rechenzentrums-Traffic (ohne VPN/Tor) setzt is_data_center=true, löst aber keine automatische Warnung aus — nutzen Sie dies als zusätzliches Signal in Ihrem eigenen Scoring.

Beispiele

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-Sperrlisten-Treffer + VPN + doppeltes Gerät

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

Authentifizierung

Verifizierung

Überwachung

Plattform

Geräte- und IP-Analyse-Bericht: Felder & Treffer

Übersicht

Wo es in API-Antworten erscheint

Schema

Match-Semantik

Statuswerte

VPN-, Proxy- und Tor-Erkennung

Beispiele

Approved

Declined — IP-Sperrlisten-Treffer + VPN + doppeltes Gerät

Verwandte Themen

​Übersicht

​Wo es in API-Antworten erscheint

​Schema

​Match-Semantik

​Statuswerte

​VPN-, Proxy- und Tor-Erkennung

​Beispiele

​Approved

​Declined — IP-Sperrlisten-Treffer + VPN + doppeltes Gerät

​Verwandte Themen

Übersicht

Wo es in API-Antworten erscheint

Schema

Match-Semantik

Statuswerte

VPN-, Proxy- und Tor-Erkennung

Beispiele

Approved

Declined — IP-Sperrlisten-Treffer + VPN + doppeltes Gerät

Verwandte Themen