> ## 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 Templat Biometrik

> Kelola templat biometrik wajah tanpa gambar yang disimpan setelah sesi dihapus di Didit: daftar, hitung, filter, periksa, dan hapus lewat API.

Prompt Biometric Templates API

Prompt Biometric Templates API
        Salin prompt ke papan klip



      
      

\<pre>

\`Manage the biometric templates my Didit application retains after deleting verification sessions.

What a biometric template is:
When an application opts in (face_retention_policy: "retain_until_user_deleted", or retain_face_embeddings: true on a delete call), deleting a KYC session deletes the session and all of its data but keeps ONE image-free face biometric template anchored to the session's User. The template keeps duplicate-face, multi-account, biometric-authentication, and list matching working for that person. It contains the numeric face template plus retention metadata only — never the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id. It is biometric data: not anonymous, not transient, and not deleted with the session. It has a finite expires_at.

Endpoints (base https://verification.didit.me, header x-api-key: YOUR_API_KEY; API keys only — Console user tokens get 403):
\- GET  /v3/biometric-templates/            — paginated list (limit/offset). Filters: vendor_data (substring, case-insensitive), vendor_user_uuid, status, source_type, retained_from, retained_to (ISO 8601), ordering (retained_at | -retained_at | expires_at | -expires_at; default -retained_at). Purged templates are not listed.
\- GET  /v3/biometric-templates/count/      — {"count": n} with the same filters.
\- GET  /v3/biometric-templates/{uuid}/     — one template.
\- DELETE /v3/biometric-templates/{uuid}/   — purge one template. 200 {"uuid": "...", "outcome": "purged" | "already_purged"}.
\- POST /v3/biometric-templates/delete/     — bulk purge. Body: {"template_uuids": ["..."]} OR {"delete_all": true} plus optional filters (vendor_data, vendor_user_uuid, status, source_type, retained_from, retained_to) that narrow delete_all. 200 {"results": [{"uuid": "...", "outcome": "purged" | "already_purged"}]}.

Template object:
\{
"uuid": "<template id>",
"vendor_user_uuid": "<User id>",
"vendor_data": "<the User's current vendor_data, resolved live>",
"source_type": "session_delete" | "automatic_retention" | "backfill",
"provenance_reference": "<opaque UUID, not the deleted session id>",
"retention_policy": "delete_with_session" | "retain_until_user_deleted",
"retention_override": true | false | null,
"retained_at": "<ISO 8601>",
"expires_at": "<ISO 8601>",
"retained_by": "<principal id: application UUID for API keys, Console member id, or service:...>",
"retained_by_type": "API_KEY" | "CONSOLE_USER" | "SYSTEM",
"instruction_class": "operational_session_delete" | "privacy_erasure",
"instruction_source": "api" | "console" | "automatic_retention" | "backfill" | "privacy_erasure" | "explicit_template_purge" | "vendor_user_delete" | "expiry" | "reconciliation" | "migration" | "system",
"instruction_id": "<your instruction_id or a Didit-generated one>",
"held_out_of_use": false,
"status": "pending" | "active" | "expired" | "held_out_of_use" | "purge_pending" | "purge_failed" | "purged",
"purged_at": null | "<ISO 8601>"
}
Only status "active" templates that are not held_out_of_use, not past expires_at, and whose User still exists take part in matching.

Purge points (all remove the template from matching and delete the stored template):
\- DELETE /v3/biometric-templates/{uuid}/ or POST /v3/biometric-templates/delete/
\- POST /v3/users/delete/ for the owning User
\- any session deletion for that User sent with deletion_instruction: "privacy_erasure"
\- automatic expiry at expires_at
Switching the application policy back to delete_with_session does NOT purge existing templates — purge them explicitly.

Failure modes:
\- 400 — {"template_uuids": ["This field is required unless delete_all is true."]} on bulk purge without a selector; invalid filter values.
\- 403 — {"detail": "You do not have permission to perform this action."} (Console user token, or key not allowed).
\- 404 — {"detail": "Biometric template not found."} on GET of an unknown or purged template.
\- 503 — {"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."} The template moves to status purge_failed and is already excluded from matching; repeat the purge.

Every retain and purge attempt, including failures, is recorded on Didit's audit trail with the acting principal, instruction class, instruction_source, instruction_id, and outcome.

For end-to-end Didit integration, paste in the full prompt at /integration/integration-prompt.`

\</pre>



      
      

Tempel ke

Secara default, menghapus sesi verifikasi juga menghapus embedding wajah yang digunakan untuk [Pencarian Wajah 1:N](https://docs.didit.me/id/core-technology/face-search/overview.md) dan deteksi duplikasi untuk sesi tersebut. Aplikasi yang memerlukan deteksi duplikasi tetap berfungsi setelah sesi dihapus dapat memilih **retensi templat biometrik**. Didit kemudian menghapus sesi dan seluruh datanya seperti biasa, dan menyimpan satu templat biometrik wajah yang dikelola secara terpisah, tanpa gambar, yang terkait dengan [Pengguna](https://docs.didit.me/id/entities/users/overview.md) pemilik sesi tersebut.Biometric Templates API memungkinkan Anda melihat dengan tepat templat mana yang dimiliki aplikasi Anda, alasannya, sampai kapan templat itu disimpan, dan menghapusnya kapan saja. Setiap templat juga dapat dilihat di Business Console pada **Lists → Biometric templates** dan di profil Pengguna pemiliknya.> [!WARNING]
>
> Templat biometrik yang disimpan adalah data biometrik. Templat ini tidak anonim, tidak bersifat sementara, dan tidak dihapus bersama sesinya. Templat tetap ada hingga tanggal kedaluwarsa yang dijadwalkan, batas waktu hukum yang berlaku lebih awal, penghapusan Pengguna, permintaan penghapusan data berdasarkan privasi, atau penghapusan eksplisit. Aktifkan retensi hanya jika instruksi pengendali data dan pemberitahuan privasi Anda mencakupnya.## Cara templat dibuat| Pemicu | `source_type` | Asal instruksi |
| - | - | - |
| Anda menghapus sesi pada aplikasi yang telah memilih retensi, atau mengirim `retain_face_embeddings: true` pada [Delete Session](https://docs.didit.me/id/sessions-api/delete-session.md) atau [Batch Delete Sessions](https://docs.didit.me/id/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` atau `console` |
| [Jendela retensi data](https://docs.didit.me/id/console/data-retention.md) umum aplikasi Anda membuat suatu sesi kedaluwarsa pada aplikasi yang telah memilih retensi | `automatic_retention` | `instruction_source: automatic_retention` |
| Backfill yang dioperasikan Didit atas instruksi Anda untuk sesi yang dihapus sebelum Anda memilih retensi | `backfill` | `instruction_source: backfill` |Retensi memerlukan referensi ke Pengguna. Sesi yang dibuat tanpa `vendor_data` tidak memiliki Pengguna, sehingga tidak dapat menyimpan templat. Penghapusan akan melaporkan `ineligible_no_vendor_user`, dan embedding dihapus bersama sesinya.## Isi templat| Disimpan | Tidak pernah disimpan |
| - | - |
| Templat wajah numerik yang digunakan untuk pencocokan | Gambar wajah, video liveness, gambar dokumen, potongan potret, dan media lainnya |
| `uuid` templat baru yang dibuat secara acak dan `provenance_reference` yang opak | ID sesi yang dihapus, nomor, keputusan, kolom identitas yang diekstrak, atau payload fitur |
| Pengguna pemilik (`vendor_user_uuid`); `vendor_data` diambil dari Pengguna saat Anda membaca templat, tidak pernah disalin | Status daftar blokir, kecocokan sebelumnya, label penipuan, atau klaim identitas lintas organisasi |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Alamat email aktor |Templat memiliki cakupan tenant dan hanya digunakan atas instruksi Anda di dalam aplikasi Anda: deteksi wajah duplikat dan multi-akun, [Autentikasi Biometrik](https://docs.didit.me/id/core-technology/biometric-auth/overview.md), serta daftar wajah Anda sendiri. Templat tidak pernah digunakan untuk pelatihan model, analitik, pencocokan lintas organisasi, sinyal bersama [Networks](https://docs.didit.me/id/console/networks.md), atau pemrosesan penipuan independen Didit.## Objek templat```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```| Kolom | Tipe | Deskripsi |
| - | - | - |
| `uuid` | UUID | ID templat. Dibuat secara acak; tidak berasal dari sesi yang dihapus atau wajahnya. |
| `vendor_user_uuid` | UUID | Pengguna pemilik. |
| `vendor_data` | string atau null | `vendor_data` Pengguna saat ini, diambil ketika Anda membaca templat. |
| `source_type` | enum | `session_delete`, `automatic_retention`, atau `backfill`. |
| `provenance_reference` | UUID | Referensi opak yang menghubungkan templat dengan jejak auditnya. Ini bukan ID sesi yang dihapus dan tidak dapat ditelusuri kembali ke sesi tersebut melalui API. |
| `retention_policy` | enum | Kebijakan aplikasi saat retensi: `delete_with_session` atau `retain_until_user_deleted`. |
| `retention_override` | boolean atau null | Nilai `retain_face_embeddings` yang dikirim pada penghapusan, atau `null` jika kebijakan yang diterapkan. |
| `retained_at` | datetime | Waktu templat dibuat. |
| `expires_at` | datetime | Waktu templat kedaluwarsa dan dihapus secara otomatis. Selalu diisi. |
| `retained_by` | string | Prinsipal yang memberikan instruksi: ID aplikasi untuk kunci API, ID anggota Console untuk tindakan Console, atau pengenal `service:` untuk retensi otomatis. Tidak pernah berupa alamat email. |
| `retained_by_type` | enum | `API_KEY`, `CONSOLE_USER`, atau `SYSTEM`. |
| `instruction_class` | enum | `operational_session_delete` atau `privacy_erasure`. |
| `instruction_source` | enum | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration`, atau `system`. |
| `instruction_id` | string | `instruction_id` yang Anda kirim pada penghapusan, atau ID yang dibuat Didit jika Anda tidak menyertakannya. |
| `held_out_of_use` | boolean | `true` hanya selama penahanan hukum berlaku. Templat yang ditahan dikecualikan dari semua pencocokan. Lihat [Penahanan hukum](#penahanan-hukum). |
| `status` | enum | Status siklus hidup, lihat di bawah. |
| `purged_at` | datetime atau null | Waktu templat dihapus. |### Status| `status` | Arti | Dalam pencocokan? |
| - | - | - |
| `pending` | Templat sedang dibuat. Jika penghapusan yang membuatnya mengembalikan `503`, ulangi penghapusan untuk menyelesaikannya. | Tidak |
| `active` | Templat ikut serta dalam pencocokan hingga `expires_at`. | Ya, kecuali `held_out_of_use` bernilai `true` atau `expires_at` telah lewat |
| `expired` | `expires_at` telah lewat dan penghapusan otomatis sedang berjalan. | Tidak |
| `held_out_of_use` | Penahanan hukum berlaku. | Tidak |
| `purge_pending` | Penghapusan sedang berjalan. | Tidak |
| `purge_failed` | Penghapusan tidak dapat selesai karena penyimpanan biometrik tidak tersedia. Ulangi penghapusan; templat tetap dikecualikan dari pencocokan sementara itu. | Tidak |
| `purged` | Templat telah dihapus. Hanya terlihat pada respons penghapusan sebagai `already_purged`; templat yang sudah dihapus tidak ditampilkan dalam daftar dan mengembalikan `404` pada detail. | Tidak |## Cara templat digunakan dalam pencocokanTemplat `active` ikut serta dalam pencocokan yang sama persis dengan wajah dari sesi langsung: deteksi duplikat otomatis saat sesi baru, [API Pencarian Wajah](https://docs.didit.me/id/standalone-apis/face-search.md) yang berdiri sendiri, [Autentikasi Biometrik](https://docs.didit.me/id/core-technology/biometric-auth/overview.md), dan daftar wajah Anda. Kecocokan dengan templat yang disimpan dilaporkan dengan `source: "retained_template"`, `vendor_user_id` dan `vendor_data` milik Pengguna tersebut, serta `biometric_template_id`. Laporan tersebut tidak pernah menyertakan id sesi, gambar pencocokan, detail identitas, atau status, karena sesi yang menghasilkan wajah tersebut sudah tidak ada. Lihat [Laporan Pencarian Wajah](https://docs.didit.me/id/core-technology/face-search/report-face-search.md).Templat yang disimpan tidak pernah masuk daftar blokir. Jika wajah dari sesi yang dihapus berada dalam daftar blokir wajah, entri daftar blokir itu memiliki entri biometrik sendiri yang independen dan siklus hidupnya sendiri: menghapus entri dari daftar akan menghapus entri daftar blokir, dan menghapus permanen templat tidak memengaruhi daftar.## Titik penghapusanSemua hal berikut menghapus templat dari pencocokan dan menghapus templat yang tersimpan:| Titik penghapusan | Caranya |
| - | - |
| Penghapusan eksplisit | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/id/management-api/biometric-templates/purge) atau [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/id/management-api/biometric-templates/batch-purge), atau **Lists → Biometric templates** di Console |
| Penghapusan Pengguna | [`POST /v3/users/delete/`](https://docs.didit.me/id/management-api/users/delete) menghapus permanen setiap templat yang terikat pada Pengguna sebelum Pengguna dihapus |
| Penghapusan privasi | Penghapusan sesi apa pun dari Pengguna tersebut yang dikirim dengan `deletion_instruction: "privacy_erasure"` menghapus permanen setiap templat yang terikat pada Pengguna, terlepas dari kebijakan aplikasi |
| Kedaluwarsa | Didit menghapus permanen templat secara otomatis setelah `expires_at` terlewati |Mengubah kebijakan aplikasi kembali ke `delete_with_session` menghentikan pembuatan templat baru, tetapi **tidak** menghapus permanen templat yang sudah ada. Hapus secara eksplisit.Penghapusan menghapus templat yang tersimpan terlebih dahulu, dan baru setelah itu menandai templat sebagai dihapus permanen. Dengan begitu, penghapusan yang mengembalikan `503` membiarkan templat dalam `purge_failed`, sudah dikecualikan dari pencocokan, dan aman untuk diulang. Mengulang penghapusan pada templat yang sudah dihapus permanen mengembalikan `already_purged`.## Jejak auditSetiap percobaan retensi dan penghapusan, termasuk kegagalan dan hasil yang tidak memenuhi syarat, dicatat dengan pelaku yang melakukan tindakan (`retained_by` / pelaku yang melakukan penghapusan dan tipenya), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference`, dan hasilnya. Kirimkan `instruction_id` Anda sendiri pada setiap penghapusan agar Anda dapat mencocokkan jejak audit Didit dengan log penghapusan Anda. Entri audit tidak pernah berisi gambar, vektor, kolom identitas, atau alamat email.## Penahanan hukumPenahanan hukum adalah pengecualian, bukan mode retensi. Didit tidak menempatkan penahanan atas inisiatifnya sendiri. Penahanan hanya dapat mengikuti instruksi terdokumentasi berdasarkan Perjanjian Pemrosesan Data Anda atau perintah mengikat dari otoritas yang berwenang. Selama penahanan berlaku, templat ditandai `held_out_of_use`: templat dikecualikan dari setiap jenis pencocokan dan dari pemulihan rutin, dan tidak pernah dapat dicari. Tidak ada API untuk membuat atau mencabut penahanan. Hubungi perwakilan Didit Anda jika Anda menerima perintah yang memengaruhi templat yang disimpan.## Izin dan autentikasiEndpoint Templat Biometrik hanya menerima kunci API aplikasi (`x-api-key`). Token pengguna Business Console ditolak dengan `403`. Pengguna Console mengelola templat melalui **Lists → Biometric templates** dengan izin `lists` mereka.## Endpoint| Endpoint | Metode | Tujuan |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/id/management-api/biometric-templates/list) | GET | Daftar berpaginasi dengan filter |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/id/management-api/biometric-templates/count) | GET | Jumlah dengan filter yang sama |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/id/management-api/biometric-templates/get) | GET | Satu templat |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/id/management-api/biometric-templates/purge) | DELETE | Hapus permanen satu templat |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/id/management-api/biometric-templates/batch-purge) | POST | Hapus permanen berdasarkan daftar id atau berdasarkan filter |## Terkait- [Hapus Sesi](https://docs.didit.me/id/sessions-api/delete-session.md)
- [Hapus Sesi secara Batch](https://docs.didit.me/id/management-api/sessions/batch-delete.md)
- [Retensi data](https://docs.didit.me/id/console/data-retention.md#retensi-templat-biometrik)
- [Wajah dan biometrik](https://docs.didit.me/id/entities/users/faces-and-biometrics.md)


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