> ## 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 búsqueda facial 1:N: detección de duplicados

> Didit busca un rostro entre tus usuarios verificados para detectar duplicados y defraudadores en listas de bloqueo. Gratis con la verificación de identidad.

La búsqueda facial es una potente función que te permite buscar un rostro concreto en todas tus sesiones de verificación de identidad aprobadas. Esta capacidad ayuda a identificar cuentas duplicadas, prevenir el fraude y reforzar tus medidas de seguridad.

Prompt de integración de la búsqueda facial
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Face Search (1:N — search a face across your enrolled users + blocklist) into your app.

\# Delivery mode
Face Search is a **standalone API**. It runs against the face index your application has enrolled through prior verifications (sessions with save_api_request=true or Passive Liveness with save_api_request=true), faces uploaded to User profiles, your face lists, and any image-free biometric templates the application retained after deleting sessions (opt-in, see /management-api/biometric-templates/overview). There is no separate Face Search workflow feature.

POST https://verification.didit.me/v3/face-search/
multipart/form-data — x-api-key: YOUR_API_KEY

Required: `user_image` (jpg/jpeg/png/tiff/webp, max 5 MB; PDFs not accepted). The image must contain at least one detectable face (largest bbox wins when multiple).

Optional: `search_type` = "most_similar" (default — dedupe / returning-user) | "blocklisted_or_approved" (blocklist screening).

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-search/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'search_type=most_similar' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```

\# Response shape (singular)
Unlike most features, Face Search returns a **singular** `face_search` object — not a plural array:
\{ request_id, face_search: { status, total_matches, matches: [{ session_id, session_number, similarity_percentage, source, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details, match_image_url, status, is_blocklisted, is_allowlisted, api_service }], user_image: {entities}, warnings: [...] } }

match.source is "session", "imported", "list_entry", or "retained_template". A retained_template hit comes from an image-free biometric template kept after the source session was deleted: session_id, session_number, status, api_service, match_image_url, and user_details are null; vendor_data and vendor_user_id identify the User; biometric_template_id is the template you can inspect or purge via /v3/biometric-templates/{id}/.

\`status` is "Declined" only when at least one blocklist match is found. Pure duplicate matches return "Approved" (informational) — apply your own dedupe policy in app logic.

\# Warnings
Face Search emits risk codes from the LogWarningChoices.FACEMATCH bucket plus blocklist/duplicate semantics:
FACE_IN_BLOCKLIST, POSSIBLE_FACE_IN_BLOCKLIST, DUPLICATED_FACE, POSSIBLE_DUPLICATED_FACE, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-search/warnings-face-search.

\# Failure modes to handle
\- HTTP 400 — no face detected in user_image. Ask the user to retake.
\- HTTP 403 — out of credits.
\- status="Declined" with FACE_IN_BLOCKLIST — definitive blocklist hit; reject.
\- POSSIBLE_FACE_IN_BLOCKLIST — borderline match below the hard threshold; route to manual review.
\- DUPLICATED_FACE — user already verified under a different vendor_data; merge or block according to policy.

\# See also
\- Canonical schema: /reference/data-models#face-search
\- Per-feature report: /core-technology/face-search/report-face-search
\- Risk catalogue: /core-technology/face-search/warnings-face-search
\- Full integration playbook: /integration/integration-prompt````

\</pre>



      
      

Paste into

La lección de la Academy sobre cómo leer un resultado de verificación llega a la búsqueda facial y las listas de bloqueo en el minuto 6:53.[Búsqueda facial y listas de bloqueo — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=413\&rel=0\&playsinline=1)![Flujo de búsqueda facial 1:N de Didit integrado con la prueba de vida para detectar duplicados y coincidencias con listas de bloqueo](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/face-search-liveness.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=0cb5738f8ceaae7891cf13631485c400)## Integración automática de la búsqueda facial> La búsqueda facial se realiza automáticamente durante las comprobaciones de prueba de vida en las sesiones de verificación, para detectar usuarios duplicados y contrastar con rostros de la lista de bloqueo.### Detección automática de duplicadosCuando un usuario completa una prueba de vida durante la verificación de identidad:- Su biometría facial se compara automáticamente con la de todos los usuarios verificados anteriormente
- El sistema identifica posibles cuentas duplicadas según la similitud facial
- Las coincidencias se marcan según los umbrales de similitud que hayas configurado
- Puedes revisar y actuar sobre los posibles usuarios duplicados### Integración con la lista de bloqueoLa búsqueda facial se integra a la perfección con la [función de lista de bloqueo](https://docs.didit.me/management-api/lists/overview.md):- Durante la verificación, los rostros se contrastan automáticamente con tu lista de bloqueo
- Si se encuentra una coincidencia con un rostro de la lista de bloqueo, la verificación se rechaza automáticamente
- Esto impide que usuarios problemáticos ya identificados creen cuentas nuevas
- Ayuda a mantener la integridad de tu proceso de verificación### El selfie tomado durante la captura del documentoMientras el usuario fotografía su documento, la cámara frontal le toma un selfie (Silent Capture). Cada vez que se evalúa el documento, ese selfie pasa por la misma búsqueda 1:N que el selfie de la prueba de vida:- Se compara con tu lista de bloqueo de rostros y con los usuarios ya aprobados en tu aplicación, con los mismos umbrales de similitud y la misma precedencia que la búsqueda de la prueba de vida.
- Una coincidencia con la lista de bloqueo genera `FRONT_CAMERA_FACE_IN_BLOCKLIST` (siempre Rechazado) o `POSSIBLE_FRONT_CAMERA_FACE_IN_BLOCKLIST` (siempre Revisión). Una coincidencia con un usuario aprobado genera `FRONT_CAMERA_DUPLICATED_FACE` o `POSSIBLE_FRONT_CAMERA_DUPLICATED_FACE`, además de `FRONT_CAMERA_DUPLICATED_FACE_NAME_MISMATCH` cuando ese usuario aprobado fue verificado con otro nombre y `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` cuando el documento de identidad de ese usuario muestra otra fecha de nacimiento. Consulta las [advertencias de la verificación de identidad](https://docs.didit.me/core-technology/id-verification/warnings-id-verification.md).
- Las coincidencias aparecen en los detalles de la sesión, en la tarjeta de verificación de identidad, y se devuelven en `id_verifications[].document_selfie_face_matches` de la [decisión de la sesión](https://docs.didit.me/sessions-api/retrieve-session.md). Usa el mismo formato de entrada que `liveness_checks[].matches`. El campo es `null` en sesiones antiguas o cuando la búsqueda no se ejecutó, y un arreglo vacío cuando se ejecutó y no encontró nada. `match_image_url` es una URL prefirmada que caduca.
- Solo se usa el rostro más grande del selfie, y solo cuando el detector está seguro de que es un rostro. Se busca un selfie por documento: el del anverso o el del reverso cuando el del anverso no contiene un rostro claro.
- El selfie solo se compara. Su plantilla biométrica nunca se almacena, así que las sesiones posteriores nunca se comparan con ella. Para vetar a una persona a partir del selfie de una sesión, añádelo a tu lista de bloqueo de rostros desde la página de la sesión.La búsqueda tiene su propio interruptor y sus propias acciones en el paso de **Verificación de identidad**, en la pestaña **Reglas** del paso (**Búsqueda facial con captura silenciosa**), o con `document_selfie_face_search_enabled` y las acciones `document_selfie_duplicated_face_*` en la [configuración de funciones del flujo](https://docs.didit.me/management-api/workflows/feature-configs.md#ocr-/-id-verification). Está activada por defecto; la acción de rostro duplicado es Aprobar por defecto (la advertencia se sigue informando) y las comprobaciones cruzadas de nombre y documento son Revisión por defecto, igual que sus equivalentes de la prueba de vida. La búsqueda necesita el selfie, así que solo se ejecuta cuando Silent Capture está activada. Desactivar la búsqueda facial en el paso de prueba de vida también desactiva esta búsqueda: esa exclusión es una decisión sobre el rostro de la persona, por lo que abarca todos los selfies de la sesión.### La regla de discrepancia de documentoLa regla de **discrepancia de documento** (`DUPLICATED_FACE_DOCUMENT_MISMATCH` para el selfie de la prueba de vida, `FRONT_CAMERA_DUPLICATED_FACE_DOCUMENT_MISMATCH` para Silent Capture) marca un rostro duplicado solo cuando el documento de identidad del usuario coincidente muestra una fecha de nacimiento distinta.
No se marca a la misma persona que presenta un documento distinto, por ejemplo un pasaporte después de un documento de identidad.
Tampoco se marca un documento renovado.
Dos sesiones que comparten el mismo número de documento del mismo país nunca se marcan.### Desactivar la búsqueda facial automáticaLa búsqueda facial automática está activada por defecto en todos los pasos de prueba de vida. Si tu postura de privacidad lo exige, puedes desactivarla por flujo desde la pestaña **Reglas** del paso de **Prueba de vida** en la Business Console (modo simple y avanzado), o con `face_search_enabled: false` en el nodo `LIVENESS` o `AGE_ESTIMATION` de la [configuración de funciones del flujo](https://docs.didit.me/management-api/workflows/feature-configs.md#liveness).Con el interruptor desactivado, el selfie de la prueba de vida se sigue puntuando para la prueba de vida y se compara 1:1 con el retrato del documento en la coincidencia facial, pero nunca llega al índice de rostros:- No se ejecuta ninguna búsqueda, así que la sesión no recibe ningún veredicto de duplicado, lista de bloqueo o lista de permitidos y su `liveness_checks[].matches` queda vacío. Las reglas de **rostro duplicado**, **discrepancia de nombre**, **discrepancia de documentos** y de rostro entre organizaciones no tienen nada sobre lo que actuar y se ocultan en la Consola.
- No se almacena ninguna plantilla biométrica del selfie, así que las sesiones posteriores no pueden compararse con esta y no hay nada que la [retención de plantillas biométricas](https://docs.didit.me/es/console/data-retention.md#retención-de-plantillas-biométricas) deba conservar después de eliminar la sesión.
- El selfie no se usa para resolver una persona biométrica compartida en las comprobaciones entre organizaciones.
- Tampoco se busca el selfie tomado durante la captura del documento (sin riesgo de lista de bloqueo ni de duplicado `FRONT_CAMERA_*`): la exclusión abarca todos los selfies de la sesión. El interruptor propio del paso de verificación de identidad (ver más arriba) también puede desactivar esa búsqueda por separado.**A qué paso pertenece el interruptor.** El interruptor está en el paso que captura el selfie, así que un paso de **prueba de vida** o de **estimación de edad** responde por sí mismo. Un paso de **coincidencia facial** no tiene uno propio: cuando un usuario repite el selfie allí (por ejemplo, después de que le pidas que reenvíe ese paso), la repetición sigue el ajuste del paso de prueba de vida, así que una exclusión también mantiene fuera del índice el nuevo selfie. Si tu flujo se ramifica en más de un paso de prueba de vida, el ajuste que se aplica es el de la rama por la que realmente pasó la sesión, y la lectura de rostros entre organizaciones sigue ese mismo paso.Los flujos existentes mantienen el comportamiento actual hasta que decidas excluirte. El cambio se aplica a las sesiones iniciadas después de guardar el flujo; las plantillas almacenadas por sesiones anteriores permanecen en el índice hasta que esas sesiones se eliminan o se purgan. El interruptor no afecta a la [API de búsqueda facial](https://docs.didit.me/standalone-apis/face-search.md) independiente, que llamas de forma explícita.> [!WARNING]
>
> Tu lista de bloqueo de rostros se aplica durante la verificación mediante la misma búsqueda 1:N. Con la búsqueda facial desactivada en el paso de prueba de vida, una persona de la lista de bloqueo no se detecta ni en ese paso ni con el selfie tomado durante la captura del documento; con la búsqueda facial con captura silenciosa desactivada en el paso de verificación de identidad, tampoco con ese selfie.### Acceso por APILa función de búsqueda facial también está disponible a través de nuestra [API](https://docs.didit.me/standalone-apis/face-search.md), que te permite:- Enviar búsquedas faciales de forma programática
- Integrar capacidades de coincidencia facial en tus propias aplicaciones
- Crear flujos personalizados de detección de fraude
- Crear sistemas automatizados de detección de duplicados## Funciones principales- **Alta precisión**: los algoritmos biométricos avanzados ofrecen resultados de coincidencia fiables
- **Umbrales configurables**: personaliza la sensibilidad de la coincidencia según tu tolerancia al riesgo
- **Análisis exhaustivo**: busca entre todos tus usuarios verificados
- **Resultados rápidos**: procesa las búsquedas con rapidez incluso con bases de datos de usuarios grandes
- **Centrada en la privacidad**: la coincidencia usa plantillas faciales numéricas limitadas a tu aplicación; el índice nunca sale de tu tenant### Umbrales configurablesPuedes personalizar la sensibilidad de la búsqueda definiendo distintos umbrales para las puntuaciones de similitud:> [!NOTE]
>
> Estos umbrales se pueden ajustar según tu tolerancia al riesgo y tus requisitos de seguridad.## Cómo funciona**1. Extracción del rostro**Cuando se inicia una búsqueda, el sistema procesa la imagen de referencia:| Proceso | Descripción |
| - | - |
| **Extracción de rasgos** | Aísla los rasgos faciales de la imagen de referencia |
| **Normalización** | Estandariza los datos faciales para una comparación coherente |
| **Validación de calidad** | Comprueba la calidad de la imagen y la nitidez del rostro |
| **Codificación vectorial** | Crea una representación vectorial matemática del rostro |**2. Algoritmo de comparación**El sistema busca en toda tu base de datos de sesiones verificadas:- Compara el vector facial de referencia con **todos los rostros registrados en tu aplicación**: rostros de sesiones, rostros subidos a perfiles de usuario, tus listas de rostros y cualquier plantilla biométrica conservada
- Emplea una arquitectura avanzada de redes neuronales optimizada para velocidad y precisión
- Admite dos modos de búsqueda: **más similares** (lista ordenada) y **en lista de bloqueo o aprobados** (filtrada por estado)
- Procesa grandes bases de datos con rapidez mediante una indexación optimizada**3. Puntuación de similitud**Para cada comparación se genera un porcentaje de similitud:| Rango de puntuación | Interpretación |
| :-: | - |
| **90%+** | Coincidencia fuerte: es muy probable que sea la misma persona |
| **70–89%** | Posible coincidencia: puede requerir revisión manual |
| **Por debajo del 70%** | Probablemente son personas distintas |Los umbrales de coincidencia que hayas configurado determinan qué resultados se marcan.**4. Entrega de resultados**El sistema devuelve un conjunto de resultados completo:- **Lista ordenada** de posibles coincidencias según la puntuación de similitud
- **Detalles de la coincidencia**, incluidos el ID de sesión, la fecha de verificación y los datos del proveedor (vendor data)
- **Porcentaje de similitud** de cada coincidencia
- **Imágenes de la coincidencia** disponibles para revisión visual
- **Estado en la lista de bloqueo** que indica si el rostro coincidente está en ella## Sesiones eliminadas y plantillas biométricas conservadasEliminar una sesión elimina por defecto su vector facial, así que la persona sale del índice y puede volver a verificarse sin que se la marque como duplicada. Las aplicaciones que eliminan sesiones poco después de aprobarlas pero aun así necesitan detectar registros repetidos pueden activar la [retención de plantillas biométricas](https://docs.didit.me/es/console/data-retention.md#retención-de-plantillas-biométricas). Didit conserva entonces una plantilla biométrica sin imágenes asociada al usuario después de eliminar la sesión, y esa plantilla participa en la búsqueda facial y en la detección automática de duplicados exactamente igual que el rostro de una sesión activa.Una coincidencia con una plantilla conservada se informa con `source: "retained_template"`, el `vendor_user_id` y el `vendor_data` del usuario propietario y un `biometric_template_id`. No incluye ID de sesión, imagen de la coincidencia, datos de identidad ni estado de sesión, porque la sesión que produjo el rostro ya no existe. Las plantillas conservadas nunca se añaden a la lista de bloqueo; las entradas de la lista de bloqueo de rostros mantienen su propia entrada biométrica independiente.La plantilla permanece hasta su caducidad programada, la eliminación del usuario, una solicitud de borrado por privacidad o una purga explícita mediante la [API de plantillas biométricas](https://docs.didit.me/management-api/biometric-templates/overview.md) o **Listas → Plantillas biométricas** en la Consola.## Porcentaje de similitudEl porcentaje de similitud es la métrica principal para determinar posibles coincidencias:- **Porcentaje alto (normalmente 90% o más)**: indica una alta probabilidad de que los rostros pertenezcan a la misma persona.
- **Porcentaje medio (70-89%)**: sugiere posibles coincidencias que pueden requerir más revisión.
- **Porcentaje bajo (por debajo del 70%)**: probablemente indica personas distintas.El umbral exacto que define una "coincidencia" se puede configurar según tus requisitos de seguridad. Subir el umbral reduce los falsos positivos, pero puede aumentar los falsos negativos.## Casos de uso- **Prevención del fraude**: identifica a los usuarios que intentan crear varias cuentas
- **KYC reforzado**: añade una capa adicional de verificación a tu proceso de KYC
- **Cumplimiento normativo**: cumple los requisitos de detección de cuentas duplicadas
- **Control de acceso**: verifica la autenticidad de los usuarios en zonas de alta seguridad
- **Fuerzas del orden**: ayuda a los organismos autorizados a identificar personas de interés


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