API de plantillas biométricas de Didit

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

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 o Eliminar sesiones en lote	`session_delete`	`instruction_source: api` o `console`
El periodo general de retención de datos 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 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 ni para el tratamiento antifraude independiente de Didit.

Objeto de plantilla

{
  "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.
`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 coincidencias

Una 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 independiente, la Autenticación biométrica 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. 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 purga

Todos 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}/` o `POST /v3/biometric-templates/delete/`, o Lists → Biometric templates en la Console
Eliminación del usuario	`POST /v3/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ía

Cada 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 legales

Una 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ón

Los 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/`	GET	Lista paginada con filtros
`/v3/biometric-templates/count/`	GET	Recuento con los mismos filtros
`/v3/biometric-templates/{template_uuid}/`	GET	Una plantilla
`/v3/biometric-templates/{template_uuid}/`	DELETE	Purgar una plantilla
`/v3/biometric-templates/delete/`	POST	Purgar por lista de ID o por filtro

Relacionado

Última modificación el 1 de noviembre de 2026

​Cómo se crea una plantilla

​Qué contiene una plantilla

​Objeto de plantilla

​Estado

​Cómo se usan las plantillas en la búsqueda de coincidencias

​Puntos de purga

​Registro de auditoría

​Retenciones legales

​Permisos y autenticación

​Endpoints

​Relacionado

Cómo se crea una plantilla

Qué contiene una plantilla

Objeto de plantilla

Estado

Cómo se usan las plantillas en la búsqueda de coincidencias

Puntos de purga

Registro de auditoría

Retenciones legales

Permisos y autenticación

Endpoints

Relacionado