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

# API Pencocokan Wajah 1:1: Perbandingan Swafoto vs ID

> Didit mencocokkan swafoto dengan foto ID via AI. $0.05/panggilan, gratis $10/bulan, skor kecocokan sub-2s untuk KYC dan onboarding.

Didit Face Match membandingkan dua wajah 1:1, biasanya swafoto dari pemeriksaan Deteksi Liveness terhadap foto potret pada dokumen identitas pengguna, dan menghasilkan skor kemiripan dari 0 hingga 100. Ambang batas yang Anda tetapkan menentukan apakah pemeriksaan tersebut lolos; API mandiri `POST /v3/face-match/` secara default menolak skor 30 atau lebih rendah.Dalam pelajaran Academy tentang membaca hasil verifikasi, bagian 6:16 membahas pemeriksaan pencocokan wajah di dalam sesi nyata.[Pencocokan wajah — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

Prompt Integrasi Pencocokan Wajah
        Salin prompt ke papan klip



      
      

\<pre>

\````# Goal
Integrate Didit Face Match (1:1 — compare two faces) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow. Face Match runs alongside ID Verification (uses the document portrait as ref) and Liveness (uses the live selfie as user_image).

1\. Add the FACE_MATCH feature to a workflow that also runs ID_VERIFICATION + LIVENESS (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `face_matches[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server)
Use when you already have two images and want a one-shot 1:1 similarity score.

POST https://verification.didit.me/v3/face-match/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (live capture) and `ref_image` (reference portrait). JPEG/PNG/WebP/TIFF, max 5 MB each.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-match/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'ref_image=@./id_portrait.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, face_match: { status, score (0-100), user_image: {entities}, ref_image: {entities}, warnings: [...] } }. `status` is "Approved" when score > face_match_score_decline_threshold (default 30), else "Declined".

\# Status enum (per face_matches[].status / face_match.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.FACEMATCH)
warnings[] risk codes include:
LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-match/warnings-face-match.

\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image or ref_image, file too large, unsupported extension.
\- status="Declined" with LOW_FACE_MATCH_SIMILARITY — the two faces do not match; do not approve.
\- NO_REFERENCE_IMAGE / NO_FACE_DETECTED — capture problems; ask the user to retry.

\# See also
\- Canonical schema: /reference/data-models#face-match
\- Per-feature report: /core-technology/face-match/report-face-match
\- Risk catalogue: /core-technology/face-match/warnings-face-match
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Tempel ke

![Ringkasan langkah-langkah verifikasi ID](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-verification-steps.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=42c64546f3495000d7ea3b10c4b5fa50)## Coba lagi & umpan balik yang dapat ditindaklanjutiDalam sesi Didit, pencocokan wajah yang gagal karena **alasan pengambilan gambar yang dapat diperbaiki** (swafoto terlalu gelap, buram, tidak berada di tengah, atau kemiripannya berada di ambang batas) tidak langsung ditolak. Pengguna diminta untuk **mencoba lagi dengan panduan**, hingga batas jumlah percobaan yang dapat dikonfigurasi — model yang sama seperti yang digunakan untuk [Deteksi Liveness](https://docs.didit.me/id/core-technology/liveness/overview.md).* **Batas percobaan** — `face_match_max_attempts` mengontrol jumlah total pengiriman pencocokan wajah per sesi. Default **3** (satu percobaan awal ditambah dua percobaan ulang), dapat dikonfigurasi per node alur kerja (rentang 1–3).

* **Umpan balik coba lagi** — selama kesempatan percobaan masih ada, kegagalan yang dapat diulang akan mempertahankan pengguna pada langkah tersebut dan mengembalikan `feedback_codes` (SDK Web dan Seluler menampilkan ini sebagai pesan panduan secara otomatis):

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **Percobaan habis** — setelah batas percobaan habis, status yang dihitung akan diterapkan (`Declined` atau `In Review`).> [!NOTE]
>
> Percobaan ulang hanya berlaku untuk **alur sesi**. Endpoint mandiri `POST /v3/face-match/` bersifat stateless dan sekali jalan — endpoint ini langsung mengembalikan skor kemiripan tanpa alokasi percobaan ulang.## Cara kerja**1. Pengambilan Gambar Cerdas**Mulai proses verifikasi dengan mudah menggunakan sistem pengambilan gambar kami yang intuitif dan berbasis AI.Pengguna mengunggah atau memotret dokumen identitas mereka dengan bantuan real-time:| Fitur | Deskripsi |
| - | - |
| **Deteksi otomatis** | Mengidentifikasi jenis dokumen dan negara penerbit secara otomatis |
| **Panduan real-time** | Petunjuk visual untuk posisi, pencahayaan, dan fokus yang optimal |
| **Pengambilan pintar** | Pengambilan gambar otomatis saat kondisi ideal — tidak memerlukan percobaan ulang manual |
| **Dukungan luas** | Paspor, SIM, kartu tanda penduduk, dan izin tinggal |> [!NOTE]
>
> *Mengapa ini penting*: Pengambilan gambar cerdas kami mengurangi hambatan bagi pengguna dan memastikan pengiriman berkualitas tinggi pada percobaan pertama, sehingga meningkatkan tingkat konversi dan kepercayaan.**2. Pemrosesan Data Lanjutan**Ekstraksi dan validasi data identitas dengan presisi tiada tanding.**Ekstraksi Data** — Teknologi mutakhir memproses semua kolom penting:| Kemampuan | Detail |
| - | - |
| **Ekstraksi kolom** | Nama lengkap, tanggal lahir, nomor dokumen, tanggal penerbitan/kedaluwarsa, kewarganegaraan, dan lainnya |
| **OCR** | Pengenalan karakter optik berpresisi tinggi untuk teks |
| **Penguraian MRZ** | Penguraian Zona yang Dapat Dibaca Mesin dan decoding kode batang |**Validasi Data**:* Melakukan pemeriksaan silang data antara zona visual, MRZ, dan kode batang untuk konsistensi
* Pencocokan format dan pola untuk mendeteksi anomali
* Kueri real-time ke database pemerintah (jika diizinkan) untuk verifikasi yang tepercaya> [!NOTE]
>
> *Mengapa ini penting*: Pemrosesan data yang komprehensif memastikan keakuratan dan menghilangkan kesalahan, memberi Anda keyakinan dalam setiap verifikasi.**3. Analisis Lanjutan**Sistem bertenaga AI kami melakukan pemeriksaan menyeluruh:- Verifikasi keaslian dokumen
- Deteksi manipulasi dan analisis integritas gambar
- Validasi fitur keamanan (hologram, watermark, dll.)
- Pencocokan templat terhadap database tersertifikasi**Deteksi Liveness dokumen** mencegah penipuan berupa:| Jenis serangan | Deskripsi |
| - | - |
| **Tangkapan layar** | Dokumen digital yang difoto dari layar |
| **Tayangan ulang layar** | Foto dokumen yang ditampilkan di layar |
| **Salinan cetak** | Reproduksi fisik dari dokumen asli |
| **Foto potret yang diubah** | Dokumen yang dimanipulasi dengan foto yang ditukar atau diedit |**4. Hasil & Integrasi Mulus**Dapatkan wawasan yang dapat ditindaklanjuti secara instan dengan opsi pengiriman yang fleksibel.**Hasil Real-Time**:| Saluran | Deskripsi |
| - | - |
| **Dasbor** | Pembaruan langsung melalui dasbor yang intuitif |
| **Webhook** | Notifikasi webhook instan untuk alur kerja otomatis |
| **REST API** | Integrasi mulus ke dalam sistem Anda yang sudah ada |**Pelaporan Komprehensif**:* Laporan PDF terperinci yang memuat hasil verifikasi dan bukti
* Jejak audit untuk kepatuhan dan pencatatan
* Opsi yang dapat disesuaikan untuk menyelaraskan dengan kebutuhan operasional Anda> [!NOTE]
>
> *Mengapa ini penting*: Hasil yang cepat dan mudah diakses memberdayakan tim Anda untuk bertindak cepat sambil menjaga proses yang aman dan dapat diaudit.***## Persyaratan dokumenUntuk keberhasilan verifikasi yang optimal, dokumen harus memenuhi standar berikut:#### Persyaratan umum- Diterbitkan oleh pemerintah dan masih berlaku dalam masa berlaku yang dikonfigurasi
- Utuh secara fisik (tidak ada kerusakan, goresan, atau noda yang mengaburkan detail)
- Semua informasi penting (nama lengkap, tanggal lahir, MRZ, dll.) terbaca dengan jelas
- Data konsisten di seluruh dokumen yang dikirimkan#### Persyaratan gambar- Foto asli dan real-time (bukan tangkapan layar, pindaian, atau salinan digital)
- Format yang didukung: JPG, JPEG, PNG, PDF
- Ukuran file maksimum: 5MB
- Gambar berwarna dengan semua sudut dokumen terlihat
- Bebas dari silau, bayangan, pengeditan digital, atau manipulasi
- Dokumen fisik wajib digunakan (ID digital hanya didukung di wilayah tertentu yang diakui secara resmi)## Pengaturan Tambahan berdasarkan Negara & Jenis DokumenKonfigurasikan aturan mendetail per negara dan jenis dokumen langsung dari konsol. Kontrol ini memungkinkan Anda menyesuaikan kriteria penerimaan dan preferensi transkripsi dengan kebutuhan kepatuhan Anda.![Panel pengaturan lanjutan pencocokan wajah Didit untuk ambang batas kemiripan dan aturan penerimaan](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-additional-settings.jpeg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4238b10a404795a61926fbdf1a3adc20)* **Mode kedaluwarsa**: Pilih cara menangani dokumen dengan tanggal kedaluwarsa yang sudah lewat.
  * **Tolak yang kedaluwarsa**: Jika tanggal kedaluwarsa dokumen lebih awal dari hari ini, tandai sebagai kedaluwarsa dan tolak.
  * **Izinkan yang kedaluwarsa**: Jangan tandai atau blokir dokumen dengan tanggal kedaluwarsa yang sudah lewat.
* **Format karakter pilihan**: Pilih cara normalisasi nama dan kolom yang diekstraksi.
  * **Utamakan karakter Latin (A–Z)**: Contoh: "Mohammed"
  * **Utamakan aksara asli (non-Latin)**: Contoh: "محمد"
* **Dukungan regional & subjenis**: Aktifkan dokumen berdasarkan wilayah dan tentukan subjenis yang dapat diterima jika suatu jenis dokumen memiliki banyak variasi.
  * Contoh: Untuk surat izin mengemudi Amerika Serikat, pilih subjenis yang tepat yang Anda terima (misalnya, Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, dll.).
  * Gunakan kontrol "Subjenis yang diterima" untuk menyertakan/mengecualikan banyak varian dengan cepat (misalnya, "128 dipilih").> Tips: Pengaturan ini berlaku per negara dan jenis dokumen, sehingga Anda dapat bersikap ketat di beberapa pasar sementara lebih permisif di pasar lainnya.


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