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

# Biometría de usuarios: búsqueda facial y lista de bloqueo

> Didit vincula la biometría facial a cada usuario: búsqueda 1:N, detección de duplicados, lista de bloqueo facial y carga manual.



Prompt de biometría facial
        Copiar el prompt al portapapeles



      
      

\<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) Auto-blocklist from declines

When a session is `DECLINED` and your workflow has auto-blocklist enabled, the associated face is added to the system face list automatically and the User entity transitions to `BLOCKED` per policy. No manual call needed.

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



      
      

Pegar en

La biometría facial es fundamental en cada entidad de usuario. Didit captura un rostro durante la [prueba de vida](https://docs.didit.me/es/core-technology/liveness/overview.md), genera un embedding vectorial y lo almacena para cuatro funciones posteriores: **búsqueda facial 1:N**, **detección de duplicados**, **aplicación de la lista de bloqueo** y **reautenticación biométrica**.> [!NOTE]
>
> Los rostros almacenados también sirven como referencia para la [Autenticación biométrica](https://docs.didit.me/es/core-technology/biometric-auth/overview.md): crea una sesión de autenticación biométrica con el `vendor_data` del usuario y omite `portrait_image`, y Didit reutiliza automáticamente el rostro almacenado (primero el rostro de una prueba de vida aprobada, después la foto del chip del pasaporte electrónico, después el retrato del documento de identidad y, por último, un rostro de perfil registrado manualmente).## Cómo se vinculan los rostros a un usuario**1. Captura durante la prueba de vida**Cuando un usuario pasa por una sesión con la prueba de vida activada, Didit captura una selfie, ejecuta la detección pasiva de vida, extrae el rostro más grande y genera un embedding vectorial para la búsqueda.**2. Almacenamiento en el perfil del usuario**El rostro queda vinculado a la sesión y a la entidad de usuario a la que pertenece. La URL del retrato aparece en el perfil del usuario como `portrait_image`.**3. Indexación para la búsqueda**El embedding se añade al índice de búsqueda. Las sesiones posteriores pueden ejecutar búsquedas 1:N contra este índice.## Búsqueda facial (1:N)La búsqueda facial te permite encontrar a un usuario subiendo una imagen y comparándola con todos los rostros registrados en tu aplicación.Casos de uso:- **Detección de duplicados** durante el onboarding: evita que la misma persona cree dos cuentas.
- **Búsqueda inversa**: identifica al usuario que aparece en un fotograma de CCTV o en una imagen de una investigación de fraude.
- **Reconocimiento de clientes recurrentes**: omite el KYC para un cliente que vuelve.La búsqueda facial se ejecuta automáticamente durante las nuevas sesiones cuando tu flujo de verificación (workflow) tiene activada la detección de duplicados. También está disponible como API independiente:- `POST /v3/face-search/`: [búsqueda facial independiente](https://docs.didit.me/es/standalone-apis/face-search.md)## Detección de duplicadosCada rostro nuevo puede compararse con los rostros ya registrados para detectar duplicados. Didit asigna a cada rostro un `approved_duplicate_status`:| Estado | Significado |
| - | - |
| `NOT_DUPLICATED` | No se encontraron coincidencias por encima del umbral de similitud |
| `DUPLICATED` | El rostro coincide con uno o más rostros de una sesión ya aprobada |Los flujos pueden configurarse para:- **Rechazar** automáticamente las sesiones marcadas como duplicadas.
- **Marcar para revisión**: derivarlas a un analista humano.
- **Solo advertir**: permitirlas, pero añadir una etiqueta de riesgo.Configúralo en la consola en *Workflows → \[tu flujo] → Face Match / Liveness → Duplicate detection*.## Lista de bloqueo de rostrosCuando una sesión se rechaza (por una regla, por un analista o por la configuración del workflow), el rostro asociado se añade automáticamente a la **lista de bloqueo de rostros** de tu aplicación. Las sesiones futuras con un rostro coincidente se rechazan.## Subir un rostro importado al perfil de un usuarioSi estás migrando desde otro proveedor de KYC, puedes crear primero el usuario y luego adjuntar una imagen facial de confianza a ese perfil. El usuario sigue identificándose por tu `vendor_data`, pero el endpoint de subida de rostros usa el id interno de usuario de Didit (`didit_internal_id`) para que el destino no sea ambiguo.**1. Crea o recupera el usuario**Invoca [`POST /v3/users/create/`](https://docs.didit.me/es/management-api/users/create) con tu `vendor_data` estable, o invoca `GET /v3/users/{vendor_data}/` si el usuario ya existe.**2. Lee didit\_internal\_id**La respuesta del usuario incluye `didit_internal_id`. Sigue usando `vendor_data` en tu propio sistema; usa `didit_internal_id` solo para los endpoints que adjuntan datos al perfil.**3. Sube el rostro**Invoca [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](https://docs.didit.me/es/management-api/users/upload-face) con una imagen facial codificada en 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"
  }'
```Los rostros de perfil importados se registran en el mismo índice facial que se usa para la detección de duplicados y la búsqueda facial. No se añaden automáticamente a la lista de bloqueo. Para bloquear a un actor malicioso conocido, sube el rostro a una lista de tipo rostro.> [!WARNING]
>
> Sube solo rostros que tengas permitido tratar según tu propio aviso de privacidad y tu acuerdo de migración. Guarda los identificadores del proveedor de origen en `metadata` o `comment` solo cuando sea seguro mostrarlos a tus operadores de cumplimiento.### Cómo se añade un rostro a la lista de bloqueo| Disparador | Acción |
| - | - |
| Sesión `DECLINED` con la lista de bloqueo automática activada | El rostro se añade a la lista de rostros del sistema y el estado del usuario pasa a `BLOCKED` |
| Un analista añade manualmente un rostro a la lista de bloqueo desde la consola | El rostro se añade y el estado del usuario se actualiza según la política |
| Alta programática mediante la Lists API | Sube la imagen facial a una lista de bloqueo de tipo rostro |### Subir un rostro a la lista de bloqueoPara bloquear a un usuario por su rostro de forma programática, sube la imagen facial a una lista de bloqueo de tipo rostro mediante el endpoint específico [Subir rostro a la lista](https://docs.didit.me/es/management-api/lists/upload-face.md). Didit extrae el embedding biométrico y lo inserta en el índice de coincidencias: cualquier sesión futura cuya selfie de prueba de vida coincida se rechaza automáticamente.> [!NOTE]
>
> La subida de un rostro al perfil y la subida de un rostro a la lista de bloqueo son operaciones distintas. Usa la subida al perfil para adjuntar a un usuario un rostro importado de confianza como evidencia y para la detección de duplicados y la búsqueda facial. Usa la [Lists API](https://docs.didit.me/es/management-api/lists/overview.md) para bloquear un rostro para que se rechace cualquier sesión futura cuya selfie coincida.### Eliminar un rostro de la lista de bloqueoElimina la entrada desde la consola en *Blocklist → Faces → acciones de la fila → Remove*, o usa el endpoint [Eliminar entrada](https://docs.didit.me/es/management-api/lists/delete-entry.md).## Plantillas biométricas conservadas tras eliminar una sesiónAl eliminar una sesión se eliminan la imagen del rostro y, de forma predeterminada, el embedding facial, por lo que la persona deja de participar en la detección de duplicados y en la Búsqueda facial. Si eliminas sesiones poco después de aprobarlas, pero aun así necesitas detectar registros repetidos, activa la [retención de plantillas biométricas](https://docs.didit.me/es/console/data-retention.md#retención-de-plantillas-biométricas) en la aplicación o envía `retain_face_embeddings: true` en la llamada de eliminación.En ese caso, Didit elimina la sesión y todos sus datos como de costumbre, y conserva una única plantilla biométrica facial sin imagen, gestionada por separado y vinculada al usuario:- Solo contiene la plantilla facial numérica y metadatos de retención. Nunca contiene la imagen del rostro, el video de la prueba de vida, los datos del documento, los campos de identidad extraídos, la decisión ni el id de la sesión eliminada.
- Participa en la detección de duplicados, la Búsqueda facial, la autenticación biométrica y tus listas de rostros exactamente igual que el rostro de una sesión activa. Las coincidencias se informan con `source: "retained_template"`, el `vendor_user_id` y los `vendor_data` del usuario, y un `biometric_template_id`.
- Es un dato biométrico con un `expires_at` finito. Se purga cuando se elimina el usuario, cuando se elimina cualquier sesión de ese usuario con `deletion_instruction: "privacy_erasure"`, cuando expira o cuando la purgas en **Lists → Biometric templates** o mediante la [API de plantillas biométricas](https://docs.didit.me/es/management-api/biometric-templates/overview.md).
- Una sesión creada sin `vendor_data` no tiene un usuario al que vincular una plantilla; al eliminarla se informa `ineligible_no_vendor_user` y el embedding se elimina junto con la sesión.
- Las plantillas conservadas nunca se añaden a una lista de bloqueo. Una entrada de la lista de bloqueo de rostros creada a partir de la sesión eliminada mantiene su propia entrada biométrica independiente y su propio ciclo de vida.Las plantillas vinculadas a un usuario aparecen en su perfil, en **Biometric templates**, con una acción para purgarlas.## Resumen del ciclo de vida de los rostros```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Declined --> Blocklisted: Auto-blocklist enabled
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```## Subir un rostro desde la consolaLos operadores de cumplimiento pueden subir rostros manualmente:1) Ve a *Users → \[user] → Actions → Upload face*.
2) Selecciona una imagen; Didit extrae el rostro más grande y guarda un nuevo registro de Face vinculado al usuario.
3) El rostro se registra como evidencia del perfil y para la detección de duplicados y la búsqueda facial. Usa la sección de lista de bloqueo cuando el objetivo sea rechazar futuras sesiones que coincidan.Esto resulta útil cuando:- Tienes un retrato conocido de un cliente verificado mediante un canal offline.
- Quieres precargar una lista de bloqueo con actores maliciosos conocidos de tu base de datos de fraude.## Privacidad y retención- Los embeddings faciales son vectores numéricos, no imágenes. Las imágenes se guardan en un almacenamiento de objetos cifrado, con acceso mediante URL firmadas. Un embedding facial es un dato biométrico.
- La retención sigue la política de [retención de datos](https://docs.didit.me/es/console/data-retention.md) de tu aplicación. Las plantillas biométricas conservadas siguen el período de [retención de plantillas biométricas](https://docs.didit.me/es/console/data-retention.md#retención-de-plantillas-biométricas), más estricto y finito.
- Al eliminar una sesión se eliminan la imagen y, de forma predeterminada, el embedding. Si tu aplicación ha activado la retención de plantillas biométricas, al eliminar una sesión se conserva una plantilla sin imagen hasta que expire o se purgue.
- Ante una solicitud para ejercer el derecho al olvido conforme al RGPD o la CCPA, elimina las sesiones de la persona con `deletion_instruction: "privacy_erasure"` o elimina el usuario: ambas opciones purgan también todas las plantillas conservadas. Las entradas de la lista de bloqueo de rostros que gestionas se mantienen hasta que las elimines.## Próximos pasos> [card] [Búsqueda facial](https://docs.didit.me/es/core-technology/face-search/overview.md)
>
> Cómo funciona la búsqueda facial 1:N.> [card] [Prueba de vida](https://docs.didit.me/es/core-technology/liveness/overview.md)
>
> Detección de prueba de vida con captura facial.> [card] [API de lista de bloqueo](https://docs.didit.me/es/management-api/lists/upload-face.md)
>
> Sube un rostro a una lista de bloqueo.> [card] [Plantillas biométricas](https://docs.didit.me/es/management-api/biometric-templates/overview.md)
>
> Plantillas conservadas tras eliminar una sesión.> [card] [Lista de bloqueo de usuarios](https://docs.didit.me/es/entities/users/blocklist.md)
>
> Cómo funciona añadir un usuario a la lista de bloqueo.


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