> ## 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 plantillas biométricas de Didit

> La API de Didit gestiona las plantillas biométricas faciales sin imagen que se conservan tras borrar sesiones: listar, filtrar, consultar y purgar.



Prompt de la API de plantillas biométricas
        Copiar el prompt al portapapeles



      
      

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



      
      

Pegar en

De forma predeterminada, al eliminar una sesión de verificación también se elimina el embedding facial que permitía la [Búsqueda facial 1:N](https://docs.didit.me/es/core-technology/face-search/overview.md) y la detección de duplicados para esa sesión. Las aplicaciones que necesitan que la detección de duplicados siga funcionando después de eliminar la sesión pueden activar la **retención de plantillas biométricas**. En ese caso, Didit elimina la sesión y todos sus datos como de costumbre, y conserva una única plantilla biométrica facial sin imágenes, gestionada por separado y vinculada al [Usuario](https://docs.didit.me/es/entities/users/overview.md) de la sesión.La API de plantillas biométricas te permite ver exactamente qué plantillas tiene tu aplicación, por qué y hasta cuándo, y eliminarlas definitivamente en cualquier momento. Cada plantilla también es visible en la Business Console, en **Lists → Biometric templates**, y en el perfil del Usuario al que pertenece.> [!WARNING]
>
> Una plantilla biométrica retenida es un dato biométrico. No es anónima, no es temporal y no se elimina con la sesión. Se conserva hasta su caducidad programada, una fecha límite anterior conforme a la legislación aplicable, la eliminación del Usuario, una solicitud de supresión por motivos de privacidad o una eliminación definitiva explícita. Activa la retención solo cuando tu instrucción como responsable del tratamiento y tu aviso de privacidad la contemplen.## Cómo se crea una plantilla| Disparador | `source_type` | De dónde procede la instrucción |
| - | - | - |
| Eliminas una sesión en una aplicación con la retención activada, o envías `retain_face_embeddings: true` en [Eliminar sesión](https://docs.didit.me/es/sessions-api/delete-session.md) o [Eliminar sesiones en lote](https://docs.didit.me/es/management-api/sessions/batch-delete.md) | `session_delete` | `instruction_source: api` o `console` |
| El [periodo general de retención de datos](https://docs.didit.me/es/console/data-retention.md) de tu aplicación hace expirar una sesión en una aplicación con la retención activada | `automatic_retention` | `instruction_source: automatic_retention` |
| Un proceso de backfill ejecutado por Didit, por instrucción tuya, para sesiones eliminadas antes de que activaras la retención | `backfill` | `instruction_source: backfill` |La retención requiere un usuario asociado. Una sesión creada sin `vendor_data` no tiene un usuario, por lo que no puede retener una plantilla; la eliminación devuelve `ineligible_no_vendor_user` y el embedding se elimina con la sesión.## Qué contiene una plantilla| Se conserva | Nunca se conserva |
| - | - |
| La plantilla facial numérica que se usa para la comparación | La imagen facial, el video de prueba de vida, las imágenes del documento, los recortes del retrato y cualquier otro contenido multimedia |
| Un nuevo `uuid` aleatorio de la plantilla y una `provenance_reference` opaca | El id, el número, la decisión, los campos de identidad extraídos o los payloads de funciones de la sesión eliminada |
| El Usuario al que pertenece (`vendor_user_uuid`); `vendor_data` se obtiene del Usuario cuando lees la plantilla y nunca se copia | El estado de la lista de bloqueo, las coincidencias anteriores, las etiquetas de fraude o las afirmaciones de identidad entre organizaciones |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Direcciones de correo electrónico de los actores |Las plantillas están aisladas por cliente y solo se usan cuando tú lo indicas dentro de tu aplicación: detección de rostros duplicados y de cuentas múltiples, [Autenticación biométrica](https://docs.didit.me/es/core-technology/biometric-auth/overview.md) y tus propias listas faciales. Nunca se usan para entrenar modelos, para analítica, para comparaciones entre organizaciones, para las señales compartidas de [Networks](https://docs.didit.me/es/console/networks.md) ni para el tratamiento antifraude independiente de Didit.## Objeto 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
}
```| Campo | Tipo | Descripción |
| - | - | - |
| `uuid` | UUID | Id de la plantilla. Se genera aleatoriamente; no se deriva de la sesión eliminada ni de su rostro. |
| `vendor_user_uuid` | UUID | El Usuario al que pertenece. |
| `vendor_data` | string o null | El `vendor_data` actual del Usuario, obtenido cuando lees la plantilla. |
| `source_type` | enum | `session_delete`, `automatic_retention` o `backfill`. |
| `provenance_reference` | UUID | Referencia opaca que vincula la plantilla con su registro de auditoría. No es el id de la sesión eliminada y no se puede vincular con ella mediante la API. |
| `retention_policy` | enum | La política de la aplicación en el momento de la retención: `delete_with_session` o `retain_until_user_deleted`. |
| `retention_override` | boolean o null | El valor de `retain_face_embeddings` enviado en la eliminación, o `null` cuando se aplicó la política. |
| `retained_at` | datetime | Cuándo se creó la plantilla. |
| `expires_at` | datetime | Cuándo expira la plantilla y se elimina definitivamente de forma automática. Siempre tiene valor. |
| `retained_by` | string | Principal que dio la instrucción: el id de la aplicación para las claves de API, el id del miembro de la Console para las acciones en la Console, o un identificador `service:` para la retención automática. Nunca es una dirección de correo electrónico. |
| `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 enviaste en la eliminación, o un id generado por Didit si lo omitiste. |
| `held_out_of_use` | boolean | `true` solo mientras se aplique una retención legal. Una plantilla retenida legalmente queda excluida de toda comparación. Consulta [Retenciones legales](#retenciones-legales). |
| `status` | enum | Estado del ciclo de vida; consulta más abajo. |
| `purged_at` | datetime o null | Cuándo se eliminó definitivamente la plantilla. |### Estado| `status` | Significado | Participa en la comparación |
| - | - | - |
| `pending` | La plantilla se está creando. Si la eliminación que la creó devolvió `503`, repite la eliminación para completarla. | No |
| `active` | La plantilla participa en la comparación hasta `expires_at`. | Sí, salvo que `held_out_of_use` sea `true` o que `expires_at` haya pasado |
| `expired` | `expires_at` ha pasado y la eliminación definitiva automática está en curso. | No |
| `held_out_of_use` | Se aplica una retención legal. | No |
| `purge_pending` | Hay una eliminación definitiva en curso. | No |
| `purge_failed` | Una eliminación definitiva no pudo completarse porque un almacén biométrico no estaba disponible. Repite la eliminación definitiva; mientras tanto, la plantilla sigue excluida de la comparación. | No |
| `purged` | La plantilla está eliminada. Solo es visible en la respuesta de la eliminación definitiva como `already_purged`; las plantillas eliminadas definitivamente no se listan y devuelven `404` en la consulta de detalle. | No |## Cómo se usan las plantillas en la búsqueda de coincidenciasUna plantilla `active` participa exactamente en las mismas búsquedas de coincidencias que el rostro de una sesión activa: la detección automática de duplicados durante las nuevas sesiones, la [API de Búsqueda facial](https://docs.didit.me/es/standalone-apis/face-search.md) independiente, la [Autenticación biométrica](https://docs.didit.me/es/core-technology/biometric-auth/overview.md) y tus listas de rostros. Una coincidencia con una plantilla conservada se informa con `source: "retained_template"`, el `vendor_user_id` y el `vendor_data` del usuario al que pertenece, y el `biometric_template_id`. Nunca incluye un id de sesión, una imagen de coincidencia, datos de identidad ni un estado, porque la sesión que generó el rostro ya no existe. Consulta el [informe de Búsqueda facial](https://docs.didit.me/es/core-technology/face-search/report-face-search.md).Una plantilla conservada nunca se añade a una lista de bloqueo. Si el rostro de la sesión eliminada estaba en una lista de bloqueo de rostros, esa entrada de la lista de bloqueo conserva su propia entrada biométrica independiente y su propio ciclo de vida: quitar la entrada de la lista elimina la entrada de la lista de bloqueo, y purgar la plantilla no afecta a la lista.## Puntos de purgaTodos los siguientes retiran la plantilla de la búsqueda de coincidencias y eliminan la plantilla almacenada:| Punto de purga | Cómo |
| - | - |
| Purga explícita | [`DELETE /v3/biometric-templates/{uuid}/`](https://docs.didit.me/es/management-api/biometric-templates/purge) o [`POST /v3/biometric-templates/delete/`](https://docs.didit.me/es/management-api/biometric-templates/batch-purge), o **Lists → Biometric templates** en la Console |
| Eliminación del usuario | [`POST /v3/users/delete/`](https://docs.didit.me/es/management-api/users/delete) purga todas las plantillas vinculadas al usuario antes de eliminar el usuario |
| Borrado por privacidad | Cualquier eliminación de una sesión de ese usuario enviada con `deletion_instruction: "privacy_erasure"` purga todas las plantillas vinculadas al usuario, independientemente de la política de la aplicación |
| Expiración | Didit purga la plantilla automáticamente cuando llega `expires_at` |Volver a cambiar la política de la aplicación a `delete_with_session` impide que se creen nuevas plantillas, pero **no** purga las existentes. Púrgalas de forma explícita.Las purgas eliminan primero la plantilla almacenada y solo después marcan la plantilla como purgada, de modo que una purga que devuelve `503` deja la plantilla en `purge_failed`, ya excluida de la búsqueda de coincidencias, y se puede repetir sin riesgo. Repetir la purga de una plantilla ya purgada devuelve `already_purged`.## Registro de auditoríaCada intento de conservación y de purga, incluidos los fallidos y los que no cumplen los requisitos, se registra con la entidad que realiza la acción (`retained_by` / entidad que realiza la purga y su tipo), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference` y el resultado. Envía tu propio `instruction_id` en las eliminaciones para poder correlacionar el registro de auditoría de Didit con tu registro de borrados. Las entradas de auditoría nunca contienen imágenes, vectores, campos de identidad ni direcciones de correo electrónico.## Retenciones legalesUna retención legal es una excepción, nunca un modo de retención. Didit no aplica retenciones por iniciativa propia; una retención solo puede derivarse de una instrucción documentada conforme a tu Acuerdo de Tratamiento de Datos o de una orden vinculante de una autoridad competente. Mientras esté vigente una retención, la plantilla se marca como `held_out_of_use`: queda excluida de cualquier tipo de comparación y de la recuperación rutinaria, y nunca admite búsquedas. No hay ninguna API para crear ni levantar retenciones. Ponte en contacto con tu representante de Didit si recibes una orden que afecte a plantillas sujetas a retención.## Permisos y autenticaciónLos endpoints de Biometric Templates solo aceptan claves de API de aplicación (`x-api-key`). Los tokens de usuario de la Business Console se rechazan con `403`. Los usuarios de la Business Console gestionan las plantillas desde **Lists → Biometric templates** con sus permisos `lists`.## Endpoints| Endpoint | Método | Propósito |
| - | - | - |
| [`/v3/biometric-templates/`](https://docs.didit.me/es/management-api/biometric-templates/list) | GET | Lista paginada con filtros |
| [`/v3/biometric-templates/count/`](https://docs.didit.me/es/management-api/biometric-templates/count) | GET | Recuento con los mismos filtros |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/es/management-api/biometric-templates/get) | GET | Una plantilla |
| [`/v3/biometric-templates/{template_uuid}/`](https://docs.didit.me/es/management-api/biometric-templates/purge) | DELETE | Purgar una plantilla |
| [`/v3/biometric-templates/delete/`](https://docs.didit.me/es/management-api/biometric-templates/batch-purge) | POST | Purgar por lista de ID o por filtro |## Relacionado- [Eliminar sesión](https://docs.didit.me/es/sessions-api/delete-session.md)
- [Eliminar sesiones en lote](https://docs.didit.me/es/management-api/sessions/batch-delete.md)
- [Retención de datos](https://docs.didit.me/es/console/data-retention.md#retención-de-plantillas-biométricas)
- [Rostros y biometría](https://docs.didit.me/es/entities/users/faces-and-biometrics.md)


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