> ## 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 Pencocokan Wajah: JSON Skor Kecocokan

> Pahami laporan pencocokan wajah 1:1 Didit: status, skor kecocokan, URL gambar, peringatan, serta lokasi data dalam respons API.

## Gambaran Umum

**Laporan pencocokan wajah** mencatat perbandingan biometrik 1:1 antara swafoto langsung yang diambil selama deteksi liveness dan gambar referensi — yang paling umum adalah foto potret yang diekstrak dari dokumen identitas. Laporan ini menghasilkan satu skor kemiripan 0–100, URL bertanda tangan untuk kedua gambar yang dibandingkan, sesi sumber untuk gambar referensi, serta setiap peringatan yang muncul dari pencocokan tersebut.

Laporan ini dibuat setelah pengguna menyelesaikan langkah deteksi liveness dan langkah dokumen dalam alur kerja (atau, untuk alur kerja berbasis potret seperti autentikasi biometrik, setelah deteksi liveness saja), atau secara langsung melalui [Face Match API](https://docs.didit.me/id/standalone-apis/face-match.md) mandiri saat Anda menyediakan sendiri dua gambar wajah apa pun.

Setiap laporan membawa `status`-nya masing-masing — terlepas dari status sesi secara keseluruhan — yang mencerminkan hasil penyelesaian langkah pencocokan wajah saja:

* **Approved** — `score` berada di atas ambang batas peninjauan dan tidak ada peringatan penolakan otomatis yang terpicu.
* **In Review** — `score` berada di antara ambang batas penolakan dan peninjauan, atau tidak ada skor yang dapat dihitung dan `face_match_not_computed_action` bernilai `REVIEW`.
* **Declined** — `score` berada pada atau di bawah ambang batas penolakan, `NO_REFERENCE_IMAGE` terpicu, atau tidak ada skor yang dapat dihitung dan `face_match_not_computed_action` bernilai `DECLINE`.
* **Resub Requested** — seorang peninjau meminta pengguna untuk mengirim ulang langkah ini dari konsol.
* **Not Finished** — langkah pencocokan wajah belum menghasilkan hasil apa pun (termasuk saat pengguna sedang mencoba ulang pengambilan gambar yang gagal).

## Lokasi kemunculan dalam respons API

Laporan pencocokan wajah dikirimkan di dalam array `face_matches[]` — **selalu berupa array JSON**, bukan objek tunggal `face_match`. Nilainya adalah `null` hingga setidaknya satu langkah pencocokan wajah telah menghasilkan data, dan beberapa entri akan muncul saat alur kerja menjalankan pencocokan wajah lebih dari sekali. Alur kerja [Adaptive Age Verification](https://docs.didit.me/id/core-technology/age-estimation/overview.md#estimasi-usia-adaptif) juga mengisinya saat fallback verifikasi identitas berjalan: entri tersebut melaporkan node estimasi usia sebagai `node_id`-nya, karena alur kerja tersebut tidak memiliki node Pencocokan Wajah tersendiri.

* **API keputusan sesi** — `GET /v3/session/{sessionId}/decision/` mengembalikan `face_matches[]` di tingkat atas. Lihat [Mengambil keputusan sesi](https://docs.didit.me/id/sessions-api/retrieve-session.md).
* **Webhook** — payload `session.status.updated` menyertakan array `face_matches[]` yang sama setelah langkah tersebut menghasilkan data. Lihat [Webhook](https://docs.didit.me/id/integration/webhooks.md).
* **Face Match API mandiri** — untuk perbandingan langsung 1:1, lihat [API mandiri Face Match](https://docs.didit.me/id/standalone-apis/face-match.md).

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

## Skema

Skema kanonik kolom demi kolom tersedia di halaman referensi [Model data](https://docs.didit.me/id/reference/data-models.md#pencocokan-wajah). Kolom-kolom di bawah ini mencerminkan skema kanonik tersebut.

| Kolom | Tipe | Deskripsi |
| - | - | - |
| `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | Status langkah pencocokan wajah (`FeatureStatusChoices`). |
| `node_id` | string \| null | Node graf alur kerja yang menghasilkan laporan ini. |
| `score` | number 0–100 \| null | Skor kemiripan biometrik, dibulatkan ke 2 desimal. `null` jika tidak ada perbandingan yang dapat dilakukan. |
| `source_image_session_id` | string \| null | UUID sesi yang potret tersimpannya menjadi gambar referensi (sumber) — diatur dalam alur berbasis potret (autentikasi biometrik, atau potret yang diberikan saat pembuatan sesi). `null` jika gambar referensi adalah potret dokumen yang diambil dalam sesi yang sama. |
| `source_image` | string (URL bertanda tangan) | Gambar referensi (biasanya potret dokumen). URL bertanda tangan dengan masa berlaku singkat — unduh segera, jangan pernah menyimpan URL tersebut secara permanen. |
| `target_image` | string (URL bertanda tangan) | Gambar target (biasanya swafoto yang diambil saat deteksi liveness). URL bertanda tangan dengan masa berlaku singkat — unduh segera, jangan pernah menyimpan URL tersebut secara permanen. |
| `warnings[]` | array | Peringatan tingkat modul. Setiap entri membawa `feature` (selalu `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, dan `node_id` — lihat [Peringatan pencocokan wajah](https://docs.didit.me/id/core-technology/face-match/warnings-face-match.md). |

## Nilai status

| Status | Arti | Efek lanjutan |
| - | - | - |
| `Approved` | Skor di atas ambang batas peninjauan dan tidak ada peringatan penolakan otomatis yang terpicu. | Dihitung sebagai pencocokan wajah yang berhasil. |
| `In Review` | Skor di atas ambang batas penolakan tetapi pada atau di bawah ambang batas peninjauan, atau tidak ada skor yang dapat dihitung (`FACE_MATCH_NOT_COMPUTED`, misalnya setelah pencarian non-dokumen yang tidak menyisakan referensi) dengan `face_match_not_computed_action` diatur ke `REVIEW`. | Sesi juga beralih ke `In Review` hingga peninjau mengambil tindakan. |
| `Declined` | Skor pada atau di bawah ambang batas penolakan, `NO_REFERENCE_IMAGE` terpicu, atau tidak ada skor yang dapat dihitung dengan `face_match_not_computed_action` diatur ke `DECLINE`. | Sesi ditolak kecuali ada cabang lain yang disetujui yang memenuhi alur kerja. |
| `Resub Requested` | Peninjau meminta pengiriman ulang langkah ini dari konsol. | Pengguna diminta untuk mengambil gambar kembali. |
| `Not Finished` | Langkah pencocokan wajah belum menghasilkan hasil apa pun (input hilang, alur kerja tidak pernah mencapai langkah perbandingan, atau pengguna masih dalam siklus coba ulang pengambilan gambar). | Cabang tidak selesai. |

Kegagalan akibat kemiripan rendah akan dicoba ulang sebelum status ditetapkan secara permanen: pengguna mendapatkan hingga `face_match_max_attempts` pengambilan gambar (secara default 3), dan hanya skor dari percobaan terakhir yang diterapkan. Aturan status kustom yang dikonfigurasikan pada node alur kerja dapat menyesuaikan status yang dihasilkan lebih lanjut, digabungkan dengan status yang ditentukan berdasarkan skor, dengan urutan prioritas `Declined` > `In Review` > `Approved`.

## Contoh

### Approved — kecocokan bersih

```json theme={null}
{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}
```

### In Review — kemiripan di ambang batas

```json theme={null}
{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}
```

### Declined — tidak ada gambar referensi untuk dibandingkan

```json theme={null}
{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}
```

## Catatan keamanan

URL bertanda tangan untuk `source_image` dan `target_image` merupakan data biometrik dan memiliki masa berlaku yang singkat. Perlakukan URL tersebut sebagai data berumur pendek: jangan menyimpannya dalam cache atau menampilkannya secara publik. Biasanya aplikasi Anda hanya membutuhkan `status` dan `score` — simpan data sesedikit mungkin untuk meminimalkan data biometrik di server Anda.

## Terkait

* [Peringatan pencocokan wajah](https://docs.didit.me/id/core-technology/face-match/warnings-face-match.md) — enum peringatan lengkap, penyebab, dan remediasi.
* [Laporan liveness](https://docs.didit.me/id/core-technology/liveness/report-liveness.md) — langkah sebelumnya yang mengambil gambar target.
* [Webhook](https://docs.didit.me/id/integration/webhooks.md) — pantau `session.status.updated` untuk menerima laporan.
* [Model data — Pencocokan wajah](https://docs.didit.me/id/reference/data-models.md#pencocokan-wajah) — skema kanonikal dengan setiap kolom.


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