> ## 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 Pencarian Wajah 1:N: Deteksi Duplikat

> Cari wajah untuk temukan duplikat dan penipu di daftar blokir. Gratis dengan verifikasi identitas Didit, respons di bawah 2 detik.

Pencarian Wajah adalah fitur canggih yang memungkinkan Anda mencari wajah tertentu di seluruh sesi verifikasi identitas Anda yang disetujui. Kemampuan ini membantu mengidentifikasi akun duplikat, mencegah penipuan, dan meningkatkan langkah keamanan Anda.

Prompt Integrasi Pencarian Wajah
        Salin prompt ke papan klip



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

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

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

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

\</pre>



      
      

Tempel ke

Pelajaran Academy tentang membaca hasil verifikasi membahas pencarian wajah dan daftar blokir pada menit 6:53.[Pencarian wajah dan daftar blokir — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Alur 1:N pencarian wajah Didit yang terintegrasi dengan liveness untuk mendeteksi duplikat dan kecocokan dengan daftar blokir](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## Integrasi Pencarian Wajah Otomatis> Pencarian Wajah dilakukan secara otomatis selama Deteksi Liveness dalam sesi verifikasi untuk mendeteksi pengguna duplikat dan memeriksa kecocokan dengan wajah dalam daftar blokir.### Deteksi Duplikat OtomatisSaat pengguna menyelesaikan Deteksi Liveness selama verifikasi identitas:- Biometrik wajah mereka secara otomatis dibandingkan dengan semua pengguna yang telah diverifikasi sebelumnya
- Sistem mengidentifikasi potensi akun duplikat berdasarkan kemiripan wajah
- Kecocokan ditandai sesuai dengan ambang batas kemiripan yang Anda konfigurasikan
- Anda dapat meninjau dan mengambil tindakan terhadap pengguna yang berpotensi duplikat### Integrasi Daftar BlokirPencarian Wajah terintegrasi secara mulus dengan [fitur daftar blokir](https://docs.didit.me/id/management-api/lists/overview.md):- Selama verifikasi, wajah secara otomatis diperiksa terhadap daftar blokir Anda
- Jika kecocokan dengan wajah dalam daftar blokir ditemukan, verifikasi secara otomatis ditolak
- Hal ini mencegah pengguna bermasalah yang telah teridentifikasi sebelumnya membuat akun baru
- Membantu menjaga integritas proses verifikasi Anda### Swafoto yang diambil selama pengambilan dokumenSaat pengguna memotret dokumen mereka, kamera depan mengambil swafoto mereka (Silent Capture). Setiap kali dokumen dievaluasi, swafoto tersebut melewati pencarian 1:N yang sama seperti swafoto Deteksi Liveness:- Swafoto dibandingkan dengan daftar blokir wajah Anda dan dengan pengguna yang telah disetujui di aplikasi Anda, dengan ambang batas kemiripan yang sama dan urutan prioritas yang sama seperti pencarian Deteksi Liveness.
- Kecocokan daftar blokir memunculkan `FRONT_CAMERA_FACE_IN_BLOCKLIST` (selalu Ditolak) atau `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (selalu Tinjau). Kecocokan dengan pengguna yang disetujui memunculkan `FRONT_CAMERA_DUPLICATED_FACE` atau `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, ditambah `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` ketika pengguna yang disetujui tersebut diverifikasi dengan nama berbeda, serta `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` ketika dokumen identitas pengguna tersebut menampilkan tanggal lahir yang berbeda. Lihat [peringatan verifikasi identitas](https://docs.didit.me/id/core-technology/id-verification/warnings-id-verification.md).
- Hasil kecocokan dicantumkan dalam detail sesi, di kartu Verifikasi Identitas, dan dikembalikan di `id_verifications[].document_selfie_face_matches` pada [keputusan sesi](https://docs.didit.me/id/sessions-api/retrieve-session.md). Format entri yang digunakan sama seperti `liveness_checks[].matches`. Kolom ini bernilai `null` untuk sesi lama atau saat pencarian tidak dijalankan, dan berupa array kosong saat dijalankan namun tidak menemukan kecocokan. `match_image_url` adalah URL bertanda tangan yang memiliki masa berlaku.
- Hanya wajah terbesar dalam swafoto yang digunakan, dan hanya jika pendeteksi yakin bahwa itu adalah wajah. Pencarian dilakukan pada satu swafoto per dokumen: sisi depan, atau sisi belakang jika swafoto sisi depan tidak memuat wajah yang jelas.
- Swafoto hanya dibandingkan. Templat biometriknya tidak pernah disimpan, sehingga sesi-sesi berikutnya tidak akan pernah dicocokkan dengannya. Untuk mencekal seseorang berdasarkan swafoto suatu sesi, tambahkan orang tersebut ke daftar blokir wajah Anda dari halaman sesi.Pencarian ini memiliki sakelar tersendiri serta tindakannya sendiri pada langkah **Verifikasi Identitas**, di tab **Aturan** langkah tersebut (**Pencarian wajah Tangkapan senyap**), atau dengan `document_selfie_face_search_enabled` dan tindakan `document_selfie_duplicated_face_*` di [konfigurasi fitur alur kerja](https://docs.didit.me/id/management-api/workflows/feature-configs.md#ocr-/-verifikasi-identitas). Fitur ini aktif secara default; tindakan wajah duplikat secara default adalah Setujui (peringatan tetap dilaporkan), sedangkan pemeriksaan silang nama dan dokumen secara default adalah Tinjau, mirip dengan padanannya pada Deteksi Liveness. Pencarian membutuhkan swafoto, sehingga hanya berjalan jika Silent Capture aktif. Menonaktifkan Pencarian Wajah pada langkah Deteksi Liveness juga akan menonaktifkan pencarian ini: pilihan untuk tidak ikut tersebut merupakan pilihan terkait wajah orang tersebut, sehingga mencakup setiap swafoto dalam sesi tersebut.### Aturan ketidakcocokan dokumenAturan **ketidakcocokan dokumen** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` untuk swafoto Deteksi Liveness, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` untuk Silent Capture) menandai wajah duplikat hanya jika dokumen identitas pengguna yang cocok menampilkan tanggal lahir yang berbeda.
Orang yang sama yang menunjukkan dokumen berbeda, misalnya paspor setelah kartu identitas, tidak akan ditandai.
Dokumen yang diperbarui juga tidak akan ditandai.
Dua sesi yang menggunakan nomor dokumen yang sama dari negara yang sama tidak akan pernah ditandai.### Menonaktifkan Pencarian Wajah otomatisPencarian Wajah otomatis aktif secara default untuk setiap langkah Deteksi Liveness. Jika kebijakan privasi Anda memerlukannya, Anda dapat menonaktifkannya per alur kerja dari tab **Aturan** pada langkah **Deteksi Liveness** di Business Console (Mode Sederhana dan Lanjutan), atau dengan `face_search_enabled: false` pada node `LIVENESS` atau `AGE_ESTIMATION` di [konfigurasi fitur alur kerja](https://docs.didit.me/id/management-api/workflows/feature-configs.md#deteksi-liveness).Dengan sakelar nonaktif, swafoto Deteksi Liveness tetap dinilai untuk liveness dan dibandingkan 1:1 terhadap foto dokumen dalam Pencocokan Wajah, tetapi tidak pernah masuk ke indeks wajah:- Tidak ada pencarian yang berjalan, sehingga sesi tidak memperoleh keputusan terkait duplikat, daftar blokir, atau daftar izin, dan `liveness_checks[].matches` miliknya tetap kosong. Aturan **Wajah duplikat**, **ketidakcocokan nama**, **ketidakcocokan dokumen**, dan aturan wajah lintas organisasi tidak memiliki data untuk diproses dan disembunyikan di Console.
- Tidak ada templat biometrik yang disimpan untuk swafoto tersebut, sehingga sesi berikutnya tidak dapat dicocokkan dengan sesi ini dan tidak ada yang perlu disimpan oleh [retensi templat biometrik](https://docs.didit.me/id/console/data-retention.md#retensi-templat-biometrik) setelah sesi dihapus.
- Swafoto tidak digunakan untuk menentukan identitas biometrik bersama untuk pemeriksaan lintas organisasi.
- Swafoto yang diambil selama pengambilan dokumen juga tidak dicari (tidak ada risiko daftar blokir atau duplikat `FRONT_CAMERA_*`): pilihan untuk tidak ikut mencakup setiap swafoto dalam sesi tersebut. Sakelar mandiri pada langkah Verifikasi Identitas (lihat di atas) juga dapat menonaktifkan pencarian tersebut secara terpisah.**Langkah tempat sakelar berada.** Sakelar berada pada langkah yang mengambil swafoto, sehingga langkah **Deteksi Liveness** atau **Estimasi Usia** berlaku untuk dirinya sendiri. Langkah **Pencocokan Wajah** tidak memiliki sakelar sendiri: saat pengguna mengambil ulang swafoto di sana - misalnya setelah Anda meminta mereka mengulangi langkah tersebut - pengambilan ulang mengikuti pengaturan langkah Deteksi Liveness, sehingga pilihan untuk tidak ikut juga menjaga swafoto baru tetap berada di luar indeks. Jika alur kerja Anda bercabang ke lebih dari satu langkah Deteksi Liveness, pengaturan yang berlaku adalah yang berada pada cabang yang benar-benar dilalui oleh sesi tersebut, dan pemeriksaan wajah lintas organisasi mengikuti langkah yang sama.Alur kerja yang ada mempertahankan perilaku saat ini hingga Anda memilih untuk tidak ikut. Perubahan ini berlaku untuk sesi yang dimulai setelah alur kerja disimpan; templat yang disimpan oleh sesi sebelumnya tetap berada di dalam indeks hingga sesi tersebut dihapus atau dibersihkan. Opsi ini tidak memengaruhi [Face Search API](https://docs.didit.me/id/standalone-apis/face-search.md) mandiri, yang Anda panggil secara eksplisit.> [!WARNING]
>
> Daftar blokir wajah Anda diterapkan selama verifikasi oleh pencarian 1:N yang sama. Dengan Pencarian Wajah nonaktif pada langkah Liveness, orang yang masuk daftar blokir tidak akan terdeteksi pada langkah tersebut maupun melalui swafoto yang diambil selama pengambilan dokumen; dengan Pencarian Wajah pada Silent Capture dinonaktifkan pada langkah Verifikasi Identitas, tidak akan terdeteksi melalui swafoto tersebut.### Akses APIFungsionalitas Pencarian Wajah juga tersedia melalui [API](https://docs.didit.me/id/standalone-apis/face-search.md) kami, memungkinkan Anda untuk:- Mengirimkan pencarian wajah secara terprogram
- Mengintegrasikan kemampuan pencocokan wajah ke dalam aplikasi Anda sendiri
- Membangun alur kerja deteksi penipuan kustom
- Membuat sistem otomatis untuk deteksi duplikat## Fitur Utama- **Akurasi Tinggi**: Algoritma biometrik canggih memberikan hasil pencocokan yang andal
- **Ambang Batas yang Dapat Dikonfigurasi**: Sesuaikan sensitivitas pencocokan berdasarkan toleransi risiko Anda
- **Pemindaian Komprehensif**: Cari di seluruh pengguna terverifikasi Anda
- **Hasil Cepat**: Proses pencarian dengan cepat bahkan dengan database pengguna yang besar
- **Berfokus pada Privasi**: Pencocokan menggunakan templat wajah numerik yang dibatasi untuk aplikasi Anda; indeks tidak pernah keluar dari tenant Anda### Ambang Batas yang Dapat DikonfigurasiAnda dapat menyesuaikan sensitivitas pencarian dengan mengatur ambang batas yang berbeda untuk skor kesamaan:> [!NOTE]
>
> Ambang batas ini dapat disesuaikan berdasarkan toleransi risiko dan persyaratan keamanan Anda.## Cara Kerja**1. Ekstraksi Wajah**Saat pencarian dimulai, sistem memproses gambar referensi:| Proses | Deskripsi |
| - | - |
| **Ekstraksi fitur** | Mengisolasi fitur wajah dari gambar referensi |
| **Normalisasi** | Menstandarisasi data wajah untuk perbandingan yang konsisten |
| **Validasi kualitas** | Memeriksa kualitas gambar dan kejelasan wajah |
| **Pengodean vektor** | Membuat representasi vektor matematis dari wajah |**2. Algoritma Perbandingan**Sistem melakukan pencarian di seluruh database sesi terverifikasi Anda:- Membandingkan vektor wajah referensi terhadap **setiap wajah yang didaftarkan dalam aplikasi Anda**: wajah sesi, wajah yang diunggah ke profil Pengguna, daftar wajah Anda, dan templat biometrik apa pun yang disimpan
- Menggunakan arsitektur jaringan neural canggih yang dioptimalkan untuk kecepatan dan akurasi
- Mendukung dua mode pencarian: **paling mirip** (daftar peringkat) dan **terdaftar di daftar blokir atau disetujui** (difilter berdasarkan status)
- Memproses database besar dengan cepat menggunakan pengindeksan yang dioptimalkan**3. Penilaian Kesamaan**Untuk setiap perbandingan, persentase kesamaan dihasilkan:| Rentang Skor | Interpretasi |
| :-: | - |
| **90%+** | Kecocokan kuat — sangat mungkin orang yang sama |
| **70–89%** | Kemungkinan cocok — mungkin memerlukan peninjauan manual |
| **Di bawah 70%** | Kemungkinan individu yang berbeda |Ambang batas kecocokan yang Anda konfigurasikan menentukan hasil mana yang ditandai.**4. Pengiriman Hasil**Sistem mengembalikan rangkaian hasil yang komprehensif:- **Daftar peringkat** potensi kecocokan yang diurutkan berdasarkan skor kesamaan
- **Detail kecocokan** termasuk ID sesi, tanggal verifikasi, dan data vendor
- **Persentase kesamaan** untuk setiap kecocokan
- **Gambar kecocokan** yang tersedia untuk peninjauan visual
- **Status daftar blokir** yang menunjukkan apakah wajah yang cocok ada di daftar blokir## Sesi yang dihapus dan templat biometrik yang disimpanMenghapus sesi secara default akan menghapus embedding wajahnya, sehingga orang tersebut keluar dari indeks dan dapat melakukan verifikasi lagi tanpa tanda duplikat. Aplikasi yang menghapus sesi segera setelah disetujui namun tetap perlu mendeteksi pendaftaran berulang dapat mengaktifkan [retensi templat biometrik](https://docs.didit.me/id/console/data-retention.md#retensi-templat-biometrik). Didit kemudian menyimpan satu templat biometrik tanpa gambar yang ditautkan ke Pengguna setelah sesi dihapus, dan templat tersebut berpartisipasi dalam Pencarian Wajah serta deteksi duplikat otomatis persis seperti wajah sesi aktif.Hasil kecocokan pada templat yang disimpan dilaporkan dengan `source: "retained_template"`, `vendor_user_id` dan `vendor_data` Pengguna pemilik, serta `biometric_template_id`. Hasil ini tidak memuat id sesi, gambar kecocokan, detail identitas, atau status sesi, karena sesi yang menghasilkan wajah tersebut sudah tidak ada lagi. Templat yang disimpan tidak pernah dimasukkan ke dalam daftar blokir; entri daftar blokir wajah menyimpan entri biometrik independennya sendiri.Templat ini tetap tersimpan hingga waktu kedaluwarsa yang dijadwalkan, penghapusan Pengguna, permintaan penghapusan privasi, atau pembersihan eksplisit melalui [Biometric Templates API](https://docs.didit.me/id/management-api/biometric-templates/overview.md) atau **Lists → Biometric templates** di Console.## Persentase KesamaanPersentase kesamaan adalah metrik utama yang digunakan untuk menentukan potensi kecocokan:- **Persentase tinggi (biasanya 90% ke atas)**: Menunjukkan kemungkinan kuat bahwa wajah-wajah tersebut milik orang yang sama.
- **Persentase sedang (70-89%)**: Menunjukkan kemungkinan kecocokan yang mungkin memerlukan peninjauan lebih lanjut.
- **Persentase rendah (di bawah 70%)**: Kemungkinan menunjukkan individu yang berbeda.Ambang batas yang tepat untuk menentukan apa yang dianggap sebagai "kecocokan" dapat dikonfigurasikan berdasarkan persyaratan keamanan Anda. Meningkatkan ambang batas akan mengurangi positif palsu tetapi dapat meningkatkan negatif palsu.## Kasus Penggunaan- **Pencegahan Penipuan**: Mengidentifikasi pengguna yang mencoba membuat beberapa akun
- **KYC Tingkat Lanjut**: Menambahkan lapisan verifikasi tambahan ke proses KYC Anda
- **Kepatuhan Regulasi**: Memenuhi persyaratan untuk mendeteksi akun duplikat
- **Kontrol Akses**: Memverifikasi keaslian pengguna untuk area dengan keamanan tinggi
- **Penegak Hukum**: Membantu instansi yang berwenang dalam mengidentifikasi individu yang menjadi perhatian


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