> ## 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 de plantilles biomètriques

> Gestiona amb Didit les plantilles facials sense imatge que la teva aplicació conserva després d'eliminar sessions: llistar, filtrar i purgar.



Prompt de l'API de plantilles biomètriques
        Copia el prompt al porta-retalls



      
      

\<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>



      
      

Enganxa a

Per defecte, eliminar una sessió de verificació també elimina l'embedding facial que alimentava la [Cerca facial 1:N](https://docs.didit.me/ca/core-technology/face-search/overview.md) i la detecció de duplicats d'aquella sessió. Les aplicacions que necessiten que la detecció de duplicats continuï funcionant després de l'eliminació de la sessió poden optar per la **retenció de plantilles biomètriques**. Didit aleshores elimina la sessió i totes les seves dades com de costum, i conserva una plantilla biomètrica facial gestionada per separat i sense imatges, vinculada a l'[usuari](https://docs.didit.me/ca/entities/users/overview.md) de la sessió.L'API de plantilles biomètriques et permet veure exactament quines plantilles té la teva aplicació, per què, fins quan, i purgar-les en qualsevol moment. Totes les plantilles també són visibles a la Business Console, a **Lists → Biometric templates**, i al perfil de l'usuari propietari.> [!WARNING]
>
> Una plantilla biomètrica retinguda és una dada biomètrica. No és anònima, no és transitòria i no s'elimina juntament amb la sessió. Es manté fins a la seva data d'expiració programada, fins al termini anterior aplicable segons la llei, fins a l'eliminació de l'usuari, fins a una sol·licitud d'esborrat per motius de privacitat o fins a una purga explícita. Activa la retenció només quan la instrucció del responsable del tractament i l'avís de privacitat la cobreixin.## Com es crea una plantilla| Disparador | `source_type` | D'on prové la instrucció |
| - | - | - |
| Elimines una sessió en una aplicació que ha optat per la retenció, o envies `retain_face_embeddings: true` a [Delete Session](https://docs.didit.me/ca/sessions-api/delete-session.md) o a [Batch Delete Sessions](https://docs.didit.me/ca/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` o `console` |
| La [finestra general de retenció de dades](https://docs.didit.me/ca/console/data-retention.md) de la teva aplicació fa expirar una sessió en una aplicació que ha optat per la retenció | `automatic_retention` | `instruction_source: automatic_retention` |
| Un backfill operat per Didit que has sol·licitat per a sessions eliminades abans que optessis per la retenció | `backfill` | `instruction_source: backfill` |La retenció requereix un ancoratge d'usuari. Una sessió creada sense `vendor_data` no té usuari, per tant no pot retenir cap plantilla; la resposta de l'eliminació indica `ineligible_no_vendor_user` i l'embedding s'elimina juntament amb la sessió.## Què conté una plantilla| Es retè | Mai es retè |
| - | - |
| La plantilla facial numèrica usada per a la coincidència | La imatge facial, el vídeo de prova de vida, les imatges del document, els retalls del retrat i qualsevol altre contingut multimèdia |
| Un `uuid` de plantilla nou i aleatori i un `provenance_reference` opac | L'id, el número, la decisió, els camps d'identitat extrets o els payloads de funcionalitats de la sessió eliminada |
| L'usuari propietari (`vendor_user_uuid`); `vendor_data` es resol a partir de l'usuari quan llegeixes la plantilla, mai es copia | L'estat de la llista de bloqueig, coincidències prèvies, etiquetes de frau o afirmacions d'identitat entre organitzacions |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Adreces de correu electrònic dels actors |Les plantilles estan circumscrites al teu tenant i només s'usen per instrucció teva dins de la teva aplicació: detecció de cares duplicades i de múltiples comptes, [Autenticació biomètrica](https://docs.didit.me/ca/core-technology/biometric-auth/overview.md) i les teves pròpies llistes facials. Mai no s'usen per a l'entrenament de models, analítica, coincidència entre organitzacions, senyals compartits de [Xarxes](https://docs.didit.me/ca/console/networks.md) ni el processament independent de frau de Didit.## Objecte de plantilla```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
}
```| Camp | Tipus | Descripció |
| - | - | - |
| `uuid` | UUID | Id de la plantilla. Generat aleatòriament; no es deriva de la sessió eliminada ni de la seva cara. |
| `vendor_user_uuid` | UUID | L'usuari propietari. |
| `vendor_data` | string o null | El `vendor_data` actual de l'usuari, resolt quan llegeixes la plantilla. |
| `source_type` | enum | `session_delete`, `automatic_retention` o `backfill`. |
| `provenance_reference` | UUID | Referència opaca que vincula la plantilla al seu registre d'auditoria. No és l'id de la sessió eliminada i no es pot resoldre fins a ella a través de l'API. |
| `retention_policy` | enum | La política de l'aplicació en el moment de la retenció: `delete_with_session` o `retain_until_user_deleted`. |
| `retention_override` | boolean o null | El valor de `retain_face_embeddings` enviat en l'eliminació, o `null` quan es va aplicar la política. |
| `retained_at` | datetime | Quan es va crear la plantilla. |
| `expires_at` | datetime | Quan la plantilla expira i es purga automàticament. Sempre està definit. |
| `retained_by` | string | L'entitat que va donar la instrucció: l'id de l'aplicació per a les claus d'API, l'id del membre de la Console per a les accions de la Console, o un identificador `service:` per a la retenció automàtica. Mai una adreça de correu electrònic. |
| `retained_by_type` | enum | `API_KEY`, `CONSOLE_USER` o `SYSTEM`. |
| `instruction_class` | enum | `operational_session_delete` o `privacy_erasure`. |
| `instruction_source` | enum | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration` o `system`. |
| `instruction_id` | string | El `instruction_id` que vas enviar en l'eliminació, o un id generat per Didit si l'havies omès. |
| `held_out_of_use` | boolean | `true` només mentre s'aplica un bloqueig legal. Una plantilla bloquejada queda exclosa de tota la coincidència. Consulta [Bloquejos legals](#retencions-legals). |
| `status` | enum | Estat del cicle de vida, vegeu a continuació. |
| `purged_at` | datetime o null | Quan es va purgar la plantilla. |### Estat| `status` | Significat | Participa en la coincidència? |
| - | - | - |
| `pending` | La plantilla s'està creant. Si l'eliminació que la va crear ha retornat `503`, repeteix l'eliminació per completar-la. | No |
| `active` | La plantilla participa en la coincidència fins a `expires_at`. | Sí, tret que `held_out_of_use` sigui `true` o que `expires_at` ja hagi passat |
| `expired` | `expires_at` ja ha passat i la purga automàtica és en curs. | No |
| `held_out_of_use` | S'aplica un bloqueig legal. | No |
| `purge_pending` | Hi ha una purga en curs. | No |
| `purge_failed` | Una purga no s'ha pogut completar perquè un magatzem biomètric no estava disponible. Repeteix la purga; mentrestant, la plantilla continua exclosa de la coincidència. | No |
| `purged` | La plantilla està eliminada. Només és visible a la resposta de la purga com a `already_purged`; les plantilles purgades no es llisten i retornen `404` en consultar-les individualment. | No |## Com s'utilitzen les plantilles en la coincidènciaUna plantilla `active` participa exactament en la mateixa coincidència que un rostre d'una sessió en curs: la detecció automàtica de duplicats en noves sessions, l'[API de cerca facial](https://docs.didit.me/ca/standalone-apis/face-search.md) independent, la [Autenticació biomètrica](https://docs.didit.me/ca/core-technology/biometric-auth/overview.md) i les teves llistes de rostres. Una coincidència amb una plantilla retinguda s'informa amb `source: "retained_template"`, el `vendor_user_id` i `vendor_data` de l'usuari propietari i el `biometric_template_id`. Mai inclou un id de sessió, una imatge de coincidència, dades d'identitat ni un estat, perquè la sessió que va generar el rostre ja no existeix. Consulta [informe de cerca facial](https://docs.didit.me/ca/core-technology/face-search/report-face-search.md).Una plantilla retinguda mai no es posa en una llista de bloqueig. Si el rostre de la sessió eliminada estava en una llista de bloqueig de rostres, aquesta entrada de la llista conserva la seva pròpia entrada biomètrica independent i el seu propi cicle de vida: eliminar l'entrada de la llista suprimeix l'entrada de bloqueig, i purgar la plantilla no afecta la llista.## Punts de purgaTots els casos següents eliminen la plantilla de la coincidència i esborren la plantilla emmagatzemada:| Punt de purga | Com |
| - | - |
| Purga explícita | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/ca/management-api/biometric-templates/purge) o [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/ca/management-api/biometric-templates/batch-purge), o **Llistes → Plantilles biomètriques** a la Console |
| Eliminació d'usuari | [`POST /v3/users/delete/`](https://docs.didit.me/ca/management-api/users/delete) purga totes les plantilles vinculades a l'usuari abans d'eliminar-lo |
| Esborrat per privacitat | Qualsevol eliminació d'una sessió d'aquest usuari enviada amb `deletion_instruction: "privacy_erasure"` purga totes les plantilles vinculades a l'usuari, independentment de la política de l'aplicació |
| Caducitat | Didit purga la plantilla automàticament quan passa `expires_at` |Tornar a establir la política de l'aplicació en `delete_with_session` deixa de crear noves plantilles, però **no** purga les existents. Purga-les explícitament.Les purgues esborren primer la plantilla emmagatzemada i només després marquen la plantilla com a purgada, de manera que una purga que retorna `503` deixa la plantilla en `purge_failed`, ja exclosa de la coincidència, i és segur repetir-la. Una purga repetida d'una plantilla ja purgada retorna `already_purged`.## Registre d'auditoriaCada intent de retenció i de purga, inclosos els errors i els resultats no elegibles, es registra amb el principal que actua (`retained_by` / el principal que realitza la purga i el tipus de principal), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` i el resultat. Envia el teu propi `instruction_id` en les eliminacions per poder correlacionar el registre d'auditoria de Didit amb el teu registre d'esborraments. Les entrades d'auditoria mai no contenen imatges, vectors, camps d'identitat ni adreces de correu electrònic.## Retencions legalsUna retenció legal és una excepció, mai un mode de retenció. Didit no aplica retencions per iniciativa pròpia; una retenció només pot derivar d'una instrucció documentada d'acord amb el teu Acord de Tractament de Dades o d'una ordre vinculant d'una autoritat competent. Mentre una retenció estigui vigent, la plantilla es marca com a `held_out_of_use`: queda exclosa de tot tipus de coincidència i de la recuperació rutinària, i mai no és cercable. No hi ha cap API per crear ni aixecar retencions. Contacta amb el teu representant de Didit si reps una ordre que afecti plantilles retingudes.## Permisos i autenticacióEls endpoints de Plantilles biomètriques accepten només claus d'API de l'aplicació (`x-api-key`). Els tokens d'usuari de la Business Console es rebutgen amb `403`. Els usuaris de la Console gestionen les plantilles a **Llistes → Plantilles biomètriques** amb els seus permisos de `lists`.## Endpoints| Endpoint | Mètode | Finalitat |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/ca/management-api/biometric-templates/list) | GET | Llista paginada amb filtres |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/ca/management-api/biometric-templates/count) | GET | Recompte amb els mateixos filtres |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ca/management-api/biometric-templates/get) | GET | Una plantilla |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/ca/management-api/biometric-templates/purge) | DELETE | Purgar una plantilla |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/ca/management-api/biometric-templates/batch-purge) | POST | Purgar per llista d'ids o per filtre |## Relacionat- [Elimina una sessió](https://docs.didit.me/ca/sessions-api/delete-session.md)
- [Elimina les sessions per lots](https://docs.didit.me/ca/management-api/sessions/batch-delete.md)
- [Conservació de dades](https://docs.didit.me/ca/console/data-retention.md#conservació-de-plantilles-biomètriques)
- [Rostres i biometria](https://docs.didit.me/ca/entities/users/faces-and-biometrics.md)


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