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

# Pencarian Wajah & Daftar Blokir Biometrik Pengguna

> Didit menautkan biometrik wajah ke entitas pengguna vendor: pencarian wajah 1:N, deteksi duplikat, penegakan daftar blokir wajah, dan unggah manual.



Prompt Biometrik Wajah
        Salin prompt ke papan klip



      
      

\<pre>

\````# Goal — search, blocklist, and act on User face biometrics

Faces are captured automatically during liveness inside a verification session, and can also be uploaded to an existing User profile when you are migrating users from another provider. You interact with biometrics through three action surfaces: **profile face upload** (attach an imported face to a User), **face search** (find a user by face), and the **Lists API** (blocklist a face so future sessions are auto-declined).

\## 1) Upload a face to an imported User profile

Use this when you already created or imported a User with `vendor_data` and have a trusted face image from your previous provider.

\```bash
\# 1. Get the Didit internal User id from vendor_data
curl https://verification.didit.me/v3/users/user-42/ \
-H "x-api-key: $DIDIT_API_KEY"

\# 2. Upload a base64-encoded face to that profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "comment": "Imported from previous KYC provider"}'
\```

Limits: max 5 faces per User, max 2 MB per image, and the image must contain a detectable face. This enrolls the face for profile evidence and future duplicate/face-search matching. It does not blocklist the face.

\## 2) Face search — 1:N

Use to detect duplicate accounts, identify a face from a CCTV frame, or recognise a returning customer before running new KYC.

\```bash
curl -X POST https://verification.didit.me/v3/face-search/ \
-H "x-api-key: $DIDIT_API_KEY" \
-F "user_image=@./selfie.jpg"
\```

Response includes match candidates with similarity scores. Wire your workflow (in the console) to auto-decline / flag / warn on duplicate hits, or call this endpoint directly from your backend before creating a session.

\## 3) Face blocklist — block a user by face

To block a known bad actor going forward, upload their face to a **face-type list** in your application. Any future session whose liveness selfie matches the embedding is auto-declined.

\```bash
\# Upload a face directly to a face-type list (no session needed)
curl -X POST https://verification.didit.me/v3/lists/$LIST_UUID/entries/face-upload/ \
-H "x-api-key: $DIDIT_API_KEY" \
-H "Content-Type: application/json" \
-d '{"image": "<base64-encoded-jpg-or-png>", "reason": "confirmed_fraud"}'
\```

If the face you want to block came from an existing session, use `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id` instead — the backend extracts the biometric and links the entry back to the session.

Remove a face from the list with the Delete entry endpoint:

\```bash
curl -X DELETE https://verification.didit.me/v3/lists/$LIST_UUID/entries/$ENTRY_UUID/ \
-H "x-api-key: $DIDIT_API_KEY"
\```

The Lists API supports face, document, email, phone, and IBAN list types. See /management-api/lists/overview for the full catalog.

\## 4) Blocklisting after a decline

Declining a session adds the face to no blocklist: the User stays `ACTIVE` and no list entry is written, so a later session with the same face is decided by the workflow's own rules, not by a list match. To block a declined subject, upload the face to a face-type list yourself with the Lists API call above — a decline never does it for you.

\## 5) Where the face lives on the User

\- `portrait_image` on the User entity is a signed URL to the latest approved selfie.
\- Manually uploaded profile faces are listed under the User profile face collection and returned by the profile face list endpoint.
\- `approved_duplicate_status` on each face is one of `NOT_DUPLICATED` / `DUPLICATED`.
\- Embeddings (numeric vectors) are stored separately from the image. Deleting a session deletes the image and, by default, the embedding. An application that opted in to biometric-template retention keeps one image-free template anchored to the User after the session is deleted; it has a finite expiry and is purged on User deletion, a privacy-erasure deletion (deletion_instruction: "privacy_erasure"), or an explicit purge via /v3/biometric-templates/ (see /management-api/biometric-templates/overview).

\## Failure modes

\- `400` from face-search / upload-face — image has no detectable face, multiple faces, or is too low-quality. Re-capture and retry.
\- `404` on Lists API — wrong `list_id` or list deleted.
\- `403` — your role lacks permission on the `lists` resource.
\- `429` — rate-limited.

\## Response shape

See /standalone-apis/face-search and /management-api/lists/upload-face for full schemas. Match objects use `similarity` (0–1) and reference the linked User `vendor_data` when known.

\## Sources of truth

\- /management-api/users/upload-face — attach an imported face to a User profile
\- /standalone-apis/face-search — face search request / response
\- /management-api/lists/upload-face — face blocklist upload
\- /management-api/lists/delete-entry — remove from list
\- /management-api/biometric-templates/overview — templates retained after session deletion
\- /core-technology/face-search/overview — search behaviour
\- /core-technology/liveness/overview — face capture during sessions
\- /integration/integration-prompt — canonical end-to-end prompt````

\</pre>



      
      

Tempel ke

Biometrik wajah merupakan inti dari setiap entitas Pengguna. Didit menangkap wajah selama [deteksi liveness](https://docs.didit.me/id/core-technology/liveness/overview.md), membuat embedding vektor, lalu menyimpannya untuk empat fitur lanjutan: **pencarian wajah 1:N**, **deteksi duplikat**, **penegakan daftar blokir**, dan **autentikasi ulang biometrik**.> [!NOTE]
>
> Wajah yang tersimpan juga berfungsi sebagai referensi untuk [Autentikasi Biometrik](https://docs.didit.me/id/core-technology/biometric-auth/overview.md): buat sesi autentikasi biometrik dengan `vendor_data` Pengguna dan hilangkan `portrait_image`, maka Didit otomatis menggunakan wajah yang tersimpan (pertama swafoto liveness yang disetujui, lalu foto chip ePassport, lalu potret dokumen identitas, dan terakhir wajah profil yang didaftarkan secara manual).## Cara wajah terhubung ke pengguna**1. Ditangkap saat liveness**Ketika Pengguna menjalani sesi dengan liveness aktif, Didit menangkap swafoto, menjalankan deteksi liveness pasif, mengekstrak wajah terbesar, dan membuat embedding vektor untuk pencarian.**2. Disimpan pada profil pengguna**Wajah dikaitkan dengan sesi dan entitas Pengguna induk. URL potret muncul pada profil pengguna sebagai `portrait_image`.**3. Diindeks untuk pencarian**Embedding ditambahkan ke indeks pencarian. Sesi berikutnya dapat menjalankan pencarian 1:N terhadap indeks ini.## Pencarian wajah (1:N)Pencarian wajah memungkinkan Anda menemukan Pengguna dengan mengunggah gambar dan mencocokkannya dengan setiap wajah yang terdaftar di aplikasi Anda.Kasus penggunaan:- **Deteksi duplikat** saat onboarding: mencegah orang yang sama membuat dua akun.
- **Pencarian terbalik**: mengidentifikasi Pengguna di balik cuplikan CCTV atau gambar dalam investigasi penipuan.
- **Pengenalan pelanggan yang kembali**: melewati KYC untuk pelanggan yang kembali.Pencarian wajah berjalan otomatis selama sesi baru jika alur kerja Anda mengaktifkan deteksi duplikat. Fitur ini juga tersedia sebagai API mandiri:- `POST /v3/face-search/` — [pencarian wajah mandiri](https://docs.didit.me/id/standalone-apis/face-search.md)## Deteksi duplikatSetiap wajah baru dapat dibandingkan dengan wajah terdaftar yang sudah ada untuk menemukan duplikat. Didit memberi setiap wajah `approved_duplicate_status`:| Status | Arti |
| - | - |
| `NOT_DUPLICATED` | Tidak ditemukan kecocokan di atas ambang kemiripan |
| `DUPLICATED` | Wajah cocok dengan satu atau lebih wajah pada sesi yang sudah disetujui |Alur kerja dapat dikonfigurasi untuk:- **Tolak** sesi yang ditandai duplikat secara otomatis.
- **Tandai untuk peninjauan**: arahkan ke analis manusia.
- **Peringatan saja**: izinkan, tetapi tambahkan tag risiko.Konfigurasikan ini di konsol pada *Workflows → \[your workflow] → Face Match / Liveness → Duplicate detection*.## Daftar blokir wajahMenolak sesi tidak menambahkan wajah ke daftar blokir mana pun. Untuk menolak sesi mendatang dengan wajah yang sama, blokir wajah tersebut secara manual: tambahkan dari [halaman Daftar blokir](https://docs.didit.me/id/console/blocklist-users.md) atau dengan [Lists API](https://docs.didit.me/id/management-api/lists/overview.md). Sesi baru yang swafoto liveness-nya kemudian cocok dengan entri tersebut akan ditolak otomatis.## Unggah wajah impor ke profil PenggunaJika Anda bermigrasi dari penyedia KYC lain, Anda dapat membuat Pengguna terlebih dahulu lalu mengaitkan gambar wajah tepercaya ke profil tersebut. Pengguna tetap diidentifikasi dengan `vendor_data` Anda, tetapi endpoint unggah wajah menggunakan id Pengguna internal Didit (`didit_internal_id`) agar targetnya tidak ambigu.**1. Buat atau ambil Pengguna**Panggil [`POST /v3/users/create/`](https://docs.didit.me/id/management-api/users/create) dengan `vendor_data` stabil Anda, atau panggil `GET /v3/users/{vendor_data}/` jika Pengguna sudah ada.**2. Baca didit\_internal\_id**Respons Pengguna menyertakan `didit_internal_id`. Tetap gunakan `vendor_data` di sistem Anda sendiri; gunakan `didit_internal_id` hanya untuk endpoint pelampiran profil.**3. Unggah wajah**Panggil [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/id/management-api/users/upload-face) dengan gambar wajah yang dienkode base64.```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```Wajah profil impor didaftarkan ke indeks wajah yang sama dengan yang digunakan untuk deteksi duplikat dan pencarian wajah. Wajah tersebut tidak otomatis masuk daftar blokir. Untuk memblokir pelaku bermasalah yang sudah diketahui, unggah wajahnya ke daftar bertipe wajah.> [!WARNING]
>
> Unggah hanya wajah yang boleh Anda proses berdasarkan pemberitahuan privasi dan perjanjian migrasi Anda. Simpan pengenal penyedia sumber dalam `metadata` atau `comment` hanya jika aman untuk ditampilkan kepada operator kepatuhan Anda.### Cara pemblokiran terjadi| Pemicu | Tindakan |
| - | - |
| Sesi `DECLINED` | Tidak ada yang ditambahkan ke daftar blokir; Pengguna tetap `ACTIVE` |
| Analis memblokir wajah secara manual dari konsol | Wajah ditambahkan, status Pengguna diperbarui sesuai kebijakan |
| Penambahan terprogram melalui Lists API | Unggah gambar wajah ke daftar blokir bertipe wajah |### Mengunggah wajah ke daftar blokirUntuk memblokir Pengguna berdasarkan wajah secara terprogram, unggah gambar wajah ke daftar blokir bertipe wajah melalui endpoint khusus [Unggah wajah ke daftar](https://docs.didit.me/id/management-api/lists/upload-face.md). Didit mengekstrak embedding biometrik dan memasukkannya ke indeks pencocokan. Setiap sesi mendatang yang swafoto liveness-nya cocok akan ditolak otomatis.> [!NOTE]
>
> Unggah wajah profil dan unggah wajah daftar blokir adalah operasi yang berbeda. Gunakan unggah profil untuk melampirkan wajah impor yang tepercaya ke Pengguna sebagai bukti, untuk deteksi duplikat, dan untuk pencarian wajah. Gunakan [Lists API](https://docs.didit.me/id/management-api/lists/overview.md) untuk memblokir wajah agar sesi yang cocok di masa mendatang ditolak.### Menghapus wajah dari daftar blokirHapus entri dari konsol pada *Blocklist → Faces → row actions → Remove*, atau gunakan endpoint [Hapus entri](https://docs.didit.me/id/management-api/lists/delete-entry.md).## Templat biometrik yang dipertahankan setelah sesi dihapusMenghapus sesi akan menghapus gambar wajah dan, secara default, embedding wajah, sehingga orang tersebut tidak lagi terdeteksi dalam deteksi duplikat dan Pencarian Wajah. Jika Anda menghapus sesi segera setelah disetujui tetapi tetap perlu mendeteksi pendaftaran ulang, aktifkan [retensi templat biometrik](https://docs.didit.me/id/console/data-retention.md#retensi-templat-biometrik) pada aplikasi, atau kirim `retain_face_embeddings: true` pada panggilan penghapusan.Didit kemudian menghapus sesi dan seluruh datanya seperti biasa, lalu menyimpan satu templat biometrik wajah yang dikelola secara terpisah dan tidak berisi gambar, yang terikat ke Pengguna:- Templat ini hanya berisi templat wajah numerik dan metadata retensi. Templat ini tidak pernah berisi gambar wajah, video liveness, data dokumen, kolom identitas yang diekstrak, keputusan, atau id sesi yang dihapus.
- Templat ini ikut serta dalam deteksi duplikat, Pencarian Wajah, autentikasi biometrik, dan daftar wajah Anda sama seperti wajah dari sesi aktif. Kecocokan dilaporkan dengan `source: "retained_template"`, `vendor_user_id` dan `vendor_data` milik Pengguna, serta `biometric_template_id`.
- Templat ini adalah data biometrik dengan `expires_at` yang memiliki batas waktu. Templat dihapus permanen saat Pengguna dihapus, saat sesi apa pun milik Pengguna tersebut dihapus dengan `deletion_instruction: "privacy_erasure"`, saat masa berlakunya habis, atau saat Anda menghapusnya di **Lists → Templat biometrik** atau melalui [Biometric Templates API](https://docs.didit.me/id/management-api/biometric-templates/overview.md).
- Sesi yang dibuat tanpa `vendor_data` tidak memiliki Pengguna untuk dikaitkan dengan templat. Saat sesi tersebut dihapus, hasilnya dilaporkan sebagai `ineligible_no_vendor_user` dan embedding dihapus bersama sesi.
- Templat yang dipertahankan tidak pernah masuk daftar blokir. Entri daftar blokir wajah yang dibuat dari sesi yang dihapus memiliki entri biometrik dan siklus hidupnya sendiri yang independen.Templat yang terikat ke Pengguna muncul di profil Pengguna di bawah **Templat biometrik**, dengan tindakan penghapusan.## Ringkasan siklus hidup wajah```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Enrolled --> Blocklisted: Face uploaded to a face-type list
    Declined --> [*]: Nothing blocklisted
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## Unggah wajah dari konsolOperator kepatuhan dapat mengunggah wajah secara manual:1) Buka *Users → \[user] → Actions → Upload face*.
2) Pilih gambar. Didit mengekstrak wajah terbesar dan menyimpan rekaman wajah baru yang ditautkan ke pengguna.
3) Wajah didaftarkan untuk bukti profil, deteksi duplikat, dan Pencarian Wajah. Gunakan area Daftar blokir jika tujuannya adalah menolak sesi yang cocok di masa mendatang.Ini berguna saat:- Anda memiliki potret yang sudah dikenal dari pelanggan yang diverifikasi melalui saluran offline.
- Anda ingin mengisi awal daftar blokir dengan pelaku kejahatan yang sudah dikenal dari basis data penipuan Anda.## Privasi dan retensi- Embedding wajah adalah vektor numerik, bukan gambar. Gambar disimpan di penyimpanan objek terenkripsi dengan akses melalui URL bertanda tangan. Embedding wajah adalah data biometrik.
- Retensi mengikuti kebijakan [retensi data](https://docs.didit.me/id/console/data-retention.md) aplikasi Anda. Templat biometrik yang dipertahankan mengikuti periode [retensi templat biometrik](https://docs.didit.me/id/console/data-retention.md#retensi-templat-biometrik) yang lebih ketat dan terbatas.
- Menghapus sesi akan menghapus gambar dan, secara default, embedding. Jika aplikasi Anda telah memilih retensi templat biometrik, menghapus sesi akan mempertahankan templat tanpa gambar hingga masa berlakunya habis atau templat dihapus permanen.
- Untuk permintaan hak untuk dilupakan berdasarkan GDPR / CCPA, hapus sesi orang tersebut dengan `deletion_instruction: "privacy_erasure"` atau hapus Pengguna. Keduanya juga menghapus permanen setiap templat yang dipertahankan. Entri daftar blokir wajah yang Anda kelola akan tetap ada sampai Anda menghapusnya.## Langkah selanjutnya> [card] [Pencarian Wajah](https://docs.didit.me/id/core-technology/face-search/overview.md)
>
> Cara kerja pencarian wajah 1:N.> [card] [Liveness](https://docs.didit.me/id/core-technology/liveness/overview.md)
>
> Deteksi Liveness yang menangkap wajah.> [card] [API Daftar Blokir](https://docs.didit.me/id/management-api/lists/upload-face.md)
>
> Unggah wajah ke daftar blokir.> [card] [Templat biometrik](https://docs.didit.me/id/management-api/biometric-templates/overview.md)
>
> Templat yang dipertahankan setelah sesi dihapus.> [card] [Daftar blokir pengguna](https://docs.didit.me/id/entities/users/blocklist.md)
>
> Cara kerja pemblokiran pengguna.


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