> ## 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 Deteksi Liveness: Skor, Metode & Pencocokan

> Laporan Liveness Didit memuat status, skor keyakinan, metode deteksi, estimasi usia, pencocokan wajah lintas sesi, dan posisinya di respons.

## Gambaran Umum

**Laporan deteksi liveness** mencakup semua hal yang diamati Didit saat memverifikasi bahwa orang yang nyata dan hidup berada di depan kamera — bukan foto cetakan, pemutaran ulang layar, atau deepfake. Laporan ini mencakup metode liveness, skor keyakinan 0–100, swafoto referensi dan video pengambilan gambar, estimasi usia opsional, metrik kualitas liveness pasif, serta pencocokan wajah lintas sesi terhadap riwayat dan daftar blokir aplikasi Anda.

Laporan dibuat setelah pengguna menyelesaikan langkah deteksi liveness dalam alur kerja (atau memanggil endpoint wajah mandiri). Didit menjalankan salah satu dari tiga metode liveness (3D aktif, kedipan cahaya, atau pasif), menilai hasil pengambilan gambar, menyaring pola spoofing yang telah diketahui, dan membandingkan wajah secara biometrik terhadap setiap wajah lain yang pernah terlihat di aplikasi Anda.

Setiap laporan memiliki `status` tersendiri — terpisah dari status sesi secara keseluruhan — yang mencerminkan hasil penyelesaian langkah deteksi liveness itu sendiri:

* **Disetujui** — wajah terdeteksi, skor liveness di atas ambang batas peninjauan, tidak ada peringatan penolakan otomatis yang terpicu.
* **Dalam Peninjauan** — satu atau beberapa peringatan yang diarahkan ke peninjauan terpicu, atau skor berada pada atau di bawah ambang batas peninjauan namun di atas ambang batas penolakan.
* **Ditolak** — kondisi penolakan otomatis terpicu (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, atau risiko usia pada alur estimasi usia), peringatan yang dapat dikonfigurasi diarahkan ke penolakan, atau skor berada pada atau di bawah ambang batas penolakan.
* **Belum Selesai** — pengguna tidak pernah menyelesaikan langkah deteksi liveness.

## Di mana laporan ini muncul dalam respons API

Laporan deteksi liveness muncul sebagai `liveness_checks[]` pada `GET /v3/session/{sessionId}/decision/` — **selalu berupa array JSON**, tidak pernah berupa objek `liveness` tunggal. Beberapa entri akan muncul jika alur kerja menjalankan deteksi liveness lebih dari satu kali (misalnya pemeriksaan utama ditambah pengambilan gambar ulang).

* **API keputusan sesi** — `GET /v3/session/{sessionId}/decision/` mengembalikan `liveness_checks[]` di tingkat teratas. Lihat [Ambil keputusan sesi](https://docs.didit.me/id/sessions-api/retrieve-session.md).
* **Webhook** — payload `session.status.updated` menyertakan array `liveness_checks[]` yang sama setelah langkah tersebut menghasilkan data. Lihat [Webhook](https://docs.didit.me/id/integration/webhooks.md).
* **API Liveness Mandiri** — lihat [API Liveness Mandiri](https://docs.didit.me/id/standalone-apis/passive-liveness.md).

> [!NOTE]
>
> Baca `response.liveness_checks[0]` dan lakukan iterasi pada array tersebut — bentuk `liveness` tunggal yang dirujuk oleh beberapa tutorial lama tidak ada pada endpoint keputusan v3.

## Skema

Skema per kolom kanonik terdapat di halaman referensi [Model data](https://docs.didit.me/id/reference/data-models.md#pemeriksaan-liveness). Kolom-kolom di bawah ini mencerminkan skema kanonik tersebut.

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | Status langkah liveness (lihat di bawah). |
| `node_id` | string \| null | Node graf alur kerja yang menghasilkan laporan ini. |
| `method` | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"` | Metode liveness yang menghasilkan pengambilan gambar ini. |
| `score` | number 0–100 \| null | Skor keyakinan liveness, dibulatkan ke 2 desimal. |
| `reference_image` | string (signed URL) \| null | Swafoto referensi yang diekstrak dari hasil pengambilan. URL bertanda tangan dengan masa berlaku terbatas. |
| `video_url` | string (signed URL) \| null | Video pengambilan Deteksi Liveness lengkap (metode aktif). URL bertanda tangan dengan masa berlaku terbatas. |
| `age_estimation` | number \| null | Estimasi usia dalam tahun untuk wajah terbesar di gambar referensi. |
| `face_quality` | number 0–100 \| null | Kualitas wajah pada liveness pasif, dinormalisasi menjadi persentase. Terisi hanya jika `method = "PASSIVE"`. |
| `face_luminance` | number 0–100 \| null | Luminansi wajah pada liveness pasif, dinormalisasi dari 0–255 menjadi persentase. Terisi hanya jika `method = "PASSIVE"`. |
| `matches[]` | array | Pencocokan Wajah lintas sesi (lihat di bawah). |
| `warnings[]` | array | Peringatan tingkat modul — lihat [Peringatan liveness](https://docs.didit.me/id/core-technology/liveness/warnings-liveness.md). Setiap entri mengikuti bentuk [Objek peringatan](https://docs.didit.me/id/reference/data-models.md#objek-peringatan) (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). |

### Pencocokan Wajah lintas sesi

`matches[]` mencantumkan wajah dalam riwayat aplikasi Anda yang melampaui ambang batas kemiripan biometrik terhadap swafoto ini — hingga 5 entri, wajah dalam daftar blokir dan daftar izin terlebih dahulu, kemudian diurutkan berdasarkan kemiripan menurun. Kandidat yang memenuhi syarat adalah wajah dalam daftar blokir, wajah dalam daftar izin, wajah dari sesi `Approved`, dan wajah yang diimpor untuk pengguna vendor Anda. Wajah milik pengguna yang sama (`vendor_data` yang sama, atau pengguna vendor yang sama jika tersedia) dikecualikan dari **seluruh** pencarian — baik deteksi duplikat maupun skrining daftar blokir.

Setiap entri meliputi:

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `session_id` | string (UUID) \| null | Sesi yang cocok. `null` jika `source` bernilai `imported` atau `list_entry`. |
| `session_number` | number \| null | Nomor sesi berurutan untuk sesi yang cocok. `null` untuk sumber non-sesi. |
| `similarity_percentage` | number 0–100 | Skor kemiripan biometrik, dibatasi antara 0–100. |
| `vendor_data` | string \| null | Data referensi Anda dari sesi yang cocok (atau pengguna vendor, untuk wajah yang diimpor). |
| `verification_date` | string (ISO 8601) \| null | Waktu saat sesi yang cocok (atau wajah yang diimpor) dibuat. |
| `user_details` | object \| null | `{ full_name, document_type, document_number }` dari KYC sesi yang cocok. Wajah yang diimpor hanya mengisi `full_name` (dua kolom dokumen bernilai `null`); `null` jika tidak ada detail yang tersimpan. |
| `match_image_url` | string (signed URL) \| null | Wajah referensi dari sesi yang cocok, wajah yang diimpor, atau entri daftar. |
| `status` | string \| null | Status sesi yang cocok (misalnya `"Approved"`). `null` untuk sumber non-sesi. |
| `is_blocklisted` | boolean | `true` jika wajah yang cocok ada di daftar blokir wajah Anda. |
| `is_allowlisted` | boolean | `true` jika wajah yang cocok ada di daftar izin wajah Anda (tindakan wajah duplikat dilewati). |
| `api_service` | string \| null | Diatur ketika wajah yang cocok berasal dari panggilan API mandiri (misalnya `"PASSIVE_LIVENESS"`); `null` untuk sesi alur kerja dan sumber non-sesi. |
| `source` | `"session" \| "imported" \| "list_entry"` | Asal wajah yang cocok: sesi verifikasi lain, wajah yang diunggah untuk pengguna vendor, atau wajah daftar izin/blokir yang dikelola organisasi. |

## Nilai status

Status berasal dari enum status fitur bersama (`FeatureStatusChoices`).

| Status | Arti | Efek lanjutan |
| - | - | - |
| `Approved` | Wajah terdeteksi, skor liveness di atas ambang batas peninjauan, tidak ada peringatan penolakan otomatis yang terpicu. | Dihitung sebagai pemeriksaan liveness yang berhasil. |
| `In Review` | Skor pada atau di bawah ambang batas peninjauan tetapi di atas ambang batas penolakan, atau peringatan yang diarahkan ke peninjauan terpicu. | Sesi juga beralih ke `In Review` hingga peninjau mengambil tindakan. |
| `Declined` | Risiko penolakan otomatis terpicu (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, atau risiko usia pada alur estimasi usia), peringatan yang dapat dikonfigurasi diarahkan ke penolakan, atau skor berada pada atau di bawah ambang batas penolakan. | Sesi ditolak kecuali ada cabang lain yang disetujui yang memenuhi alur kerja. |
| `Not Finished` | Pengguna meninggalkan langkah liveness (atau kegagalan pengambilan gambar yang dapat dicoba lagi sedang menunggu percobaan berikutnya). | Cabang liveness tidak menghasilkan hasil. |
| `Resub Requested` | Peninjau meminta pengiriman ulang langkah ini dari konsol. | Bersifat sementara — diganti setelah pengguna mengambil ulang gambar. |

## Contoh

### Approved — pengambilan active-3D bersih

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### In Review — passive liveness, pengambilan berkualitas rendah, dan kemungkinan duplikat

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

Di sini kualitas wajah (12.4) berada di bawah ambang batas peninjauan default (15), luminansi (18.7) berada di bawah batas minimum default (20), dan tindakan wajah duplikat pada alur kerja diatur ke Peninjauan — sehingga ketiga peringatan membawa `log_type: "warning"` dan laporan berstatus `In Review`.

## Catatan keamanan

Video liveness dan swafoto merupakan data biometrik — URL bertanda tangan bersifat sementara dan akan kedaluwarsa (setelah 4 jam secara default). Perlakukan video dan swafoto tersebut sebagai data berumur pendek: jangan simpan dalam cache atau tampilkan ke publik. Biasanya aplikasi Anda hanya membutuhkan `status`, `score`, dan peringatan — simpan seminimal mungkin untuk meminimalkan data biometrik di server Anda.

## Terkait

* [Peringatan liveness](https://docs.didit.me/id/core-technology/liveness/warnings-liveness.md) — enum peringatan lengkap, penyebab, dan remediasi.
* [Webhook](https://docs.didit.me/id/integration/webhooks.md) — dengarkan `session.status.updated` untuk menerima laporan.
* [Model data — Pemeriksaan liveness](https://docs.didit.me/id/reference/data-models.md#pemeriksaan-liveness) — skema kanonis beserta setiap kolomnya.
* [Laporan pencocokan wajah](https://docs.didit.me/id/core-technology/face-match/report-face-match.md) — pencocokan wajah 1:1 pendamping terhadap potret dokumen.


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