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

# Laporan Analisis Perangkat & IP: Kolom & Kecocokan

> Parse laporan Analisis Perangkat & IP Didit: geolokasi, fingerprint perangkat, flag VPN/Tor/proxy, jarak dokumen-vs-IP, & kecocokan perangkat duplikat.

## Gambaran Umum

Analisis Perangkat & IP memprofilkan setiap sesi berdasarkan geolokasi IP, sidik jari perangkat, browser/OS, dan tipe jaringan.
Geolokasi, pengayaan risiko jaringan, pencocokan perangkat, dan pemeriksaan integritas perangkat jarak jauh berjalan secara asinkron saat pengguna menyelesaikan verifikasi.
Pengamatan perangkat dan IP tetap tersedia saat analisis sedang diproses; kolom geolokasi dapat kosong hingga hasil tersedia, atau saat alamat tersebut bukan alamat publik.
Jika alur kerja Anda menggunakan pemeriksaan ini untuk menentukan hasil atau memilih langkah berikutnya, sesi tetap berstatus `In Progress` hingga hasil yang diperlukan tersedia.
Jika analisis yang diperlukan tetap tidak tersedia setelah jumlah percobaan ulang yang dibatasi, sesi akan beralih ke `In Review` untuk keputusan manual.
Kegagalan pengayaan opsional tidak menghalangi penyelesaian, dan keputusan manual tetap bersifat otoritatif.
Fitur ini menghasilkan:

* Blok **geolokasi IP** (negara, negara bagian/provinsi, kota, garis lintang/garis bujur, zona waktu) yang diperoleh dari IP publik.
* **Flag risiko jaringan** — `is_vpn_or_tor` dan `is_data_center` — untuk mendeteksi upaya penyamaran (VPN, node keluar Tor, penyedia hosting, layanan anonimisasi).
* **Kalkulasi jarak lintas dokumen** — jarak garis lurus dalam km antara lokasi IP, lokasi dokumen identitas, dan lokasi dokumen bukti alamat.
* **Pencocokan lintas sesi** — saat alamat atau identitas perangkat yang sama muncul di berbagai sesi milik pengguna yang berbeda (dikelompokkan berdasarkan `vendor_data`).
* **Pemulihan sidik jari perangkat** — sinyal pemulihan berkeyakinan tinggi yang menautkan sesi bahkan setelah pengguna menghapus penyimpanan, beralih ke mode penyamaran, atau menginstal ulang aplikasi.

![Tangkapan layar laporan Analisis Perangkat dan IP Didit dengan geolokasi, sidik jari perangkat, dan flag risiko](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)

## Tempat kemunculannya dalam respons API

Endpoint keputusan mengembalikan Analisis Perangkat & IP sebagai array **`ip_analyses[]`** di `GET /v3/session/{sessionId}/decision/`. Entri merupakan pengamatan `Location` yang dideduplikasi berdasarkan (`node_id`, `ip_address`, `device_fingerprint`) — satu node dapat menghasilkan beberapa entri jika IP atau perangkat pengguna berubah di tengah sesi.

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

Bentuk di bawah mencerminkan skema kanonik — lihat [Model data](https://docs.didit.me/id/reference/data-models.md#analisis-ip).

## Skema

Lihat [Analisis Perangkat & IP dalam referensi Model Data](https://docs.didit.me/id/reference/data-models.md#analisis-ip) untuk skema kanoniknya.

```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'
}
```

### Semantik pencocokan

`match_source` memberi tahu Anda bagaimana kecocokan dicapai, dan `confidence` menilai seberapa besar kemungkinan hasil tersebut *salah* (`confidence = 1 - P(false positive)`):

| `match_source` | Arti | `confidence` | `match_mode` |
| - | - | - | - |
| `ip_address` | IP bersama — kolokasi jaringan, yang tidak pernah merupakan klaim identitas perangkat. | `0.0` | `co_occurrence` |
| `persistent_id` | Pengidentifikasi perangkat persisten yang sama persis dengan yang tersimpan. | `1.0` | `deterministic` |
| `legacy_fp` | Hash sidik jari perangkat `didit-fp-*` lama. | `0.5` | `probabilistic` |
| `recovered_high` | Hasil pemulihan sidik jari berbasis pencocokan fuzzy dengan tingkat keyakinan tinggi setelah melewati pemeriksaan wajib yang ketat. | `1.0` jika berbasis perangkat keras, jika tidak `< 1.0`, ditingkatkan saat TLS JA4 dan negara IP cocok secara independen | `deterministic` atau `probabilistic` |

Kandidat pemulihan berkeyakinan lebih rendah hanya muncul sebagai peringatan risiko — tidak pernah dalam `matches[]`. Pencocokan IP dan pencocokan perangkat masing-masing dibatasi maksimal 5, sehingga array menampung paling banyak 10 entri.

## Nilai status

Status adalah nilai `FeatureStatusChoices` tingkat fitur. Setiap peringatan yang terpicu dipetakan ke tindakan yang dikonfigurasikan untuknya pada node alur kerja; tindakan terkuat yang akan diterapkan.

| Nilai | Arti |
| - | - |
| `Not Finished` | Node analisis IP belum selesai untuk sesi ini (default). |
| `Approved` | Tidak ada peringatan yang terpicu, atau setiap peringatan yang terpicu dikonfigurasi ke Tanpa tindakan. |
| `In Review` | Setidaknya satu peringatan yang terpicu dikonfigurasi ke Peninjauan (lihat [peringatan](https://docs.didit.me/id/core-technology/ip-analysis/warnings-ip-analysis.md)). |
| `Declined` | Peringatan daftar blokir terpicu (`IP_ADDRESS_IN_BLOCKLIST` atau `DEVICE_FINGERPRINT_IN_BLOCKLIST` — selalu tolak), atau peringatan yang dapat dikonfigurasi diatur ke Tolak untuk alur kerja Anda. |
| `Resub Requested` | Peninjau meminta pengiriman ulang untuk langkah ini. |

Aturan status kustom yang dikonfigurasikan pada node analisis IP dapat menyesuaikan status yang dihasilkan lebih lanjut.

## Deteksi VPN, proxy, dan Tor

`is_vpn_or_tor` dan `is_data_center` adalah flag boolean independen yang dikembalikan untuk setiap sesi. Saat `is_vpn_or_tor` bernilai `true`, Didit juga memunculkan peringatan `PRIVATE_NETWORK_DETECTED` sehingga tim Anda dapat mengambil tindakan melalui konfigurasi alur kerja. Lalu lintas yang hanya berasal dari pusat data (tanpa VPN/Tor) menetapkan `is_data_center=true` tetapi tidak memicu peringatan otomatis — gunakan ini sebagai sinyal tambahan dalam penilaian Anda sendiri.

## Contoh

### Disetujui

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

### Ditolak — kecocokan daftar blokir IP + VPN + perangkat duplikat

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

## Terkait

* [Peringatan analisis Perangkat & IP](https://docs.didit.me/id/core-technology/ip-analysis/warnings-ip-analysis.md) — setiap kode peringatan yang dapat dimunculkan oleh analisis IP
* [Gambaran umum analisis Perangkat & IP](https://docs.didit.me/id/core-technology/ip-analysis/overview.md) — apa saja yang diukur oleh setiap blok
* [Model data — Analisis IP](https://docs.didit.me/id/reference/data-models.md#analisis-ip) — skema kanonik
* [Webhook](https://docs.didit.me/id/integration/webhooks.md) — `status.updated` memuat payload analisis IP yang sama


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