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

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

> Didits Geräte- und IP-Analyse-Bericht liefert Geolokalisierung, Geräte-Fingerprints, VPN-/Tor-Flags, Distanzabgleiche und Duplikattreffer.

## Ü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](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/ip-analysis-report.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=5d4877664a7c89384ee32d4a5cb6949b)

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

```text theme={null}
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](https://docs.didit.me/de/reference/data-models.md#ip-analyse).

## Schema

Siehe [Geräte- und IP-Analyse in der Datenmodell-Referenz](https://docs.didit.me/de/reference/data-models.md#ip-analyse) für das kanonische 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-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](https://docs.didit.me/de/core-technology/ip-analysis/warnings-ip-analysis.md)). |
| `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

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

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

## Verwandte Themen

* [Warnungen der Geräte- und IP-Analyse](https://docs.didit.me/de/core-technology/ip-analysis/warnings-ip-analysis.md) — jeder Warncode, den die IP-Analyse ausgeben kann
* [Übersicht zur Geräte- und IP-Analyse](https://docs.didit.me/de/core-technology/ip-analysis/overview.md) — was die einzelnen Blöcke erfassen
* [Datenmodelle — IP-Analyse](https://docs.didit.me/de/reference/data-models.md#ip-analyse) — kanonisches Schema
* [Webhooks](https://docs.didit.me/de/integration/webhooks.md) — `status.updated` überträgt dieselbe IP-Analyse-Payload


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.