> ## 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 coincidencia facial 1:1: selfie frente a documento

> La coincidencia facial de Didit compara un selfie en vivo con el retrato del documento con IA. $0.05 por llamada, $10 gratis al mes, resultado en menos de 2 s.

La coincidencia facial de Didit compara dos rostros 1:1, normalmente el selfie de una comprobación de prueba de vida con el retrato del documento de identidad del usuario, y devuelve una puntuación de similitud de 0 a 100. Los umbrales que definas deciden si la comprobación se supera; la API independiente `POST /v3/face-match/` rechaza por defecto una puntuación de 30 o menos.En la lección de Academy sobre cómo leer el resultado de una verificación, el capítulo del minuto 6:16 trata la comprobación de coincidencia facial dentro de una sesión real.[Coincidencia facial — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

Prompt de integración de la coincidencia facial
        Copy prompt to clipboard



      
      

\<pre>

\````# Goal
Integrate Didit Face Match (1:1 — compare two faces) into your app. Pick ONE mode.

\# Mode A — Session-based
Use this when the user goes through a hosted Didit flow. Face Match runs alongside ID Verification (uses the document portrait as ref) and Liveness (uses the live selfie as user_image).

1\. Add the FACE_MATCH feature to a workflow that also runs ID_VERIFICATION + LIVENESS (Business Console or POST /v3/workflows/).
2\. Create a session — POST /v3/session/ with { workflow_id, vendor_data, callback }. See /sessions-api/create-session.
3\. Open session.url for the user (or mount the Web/Mobile SDK).
4\. Fetch the decision — GET /v3/session/{sessionId}/decision/ or subscribe to session.status.updated.

Decision surface: `face_matches[]` array on the decision payload.

\# Mode B — Standalone API (server-to-server)
Use when you already have two images and want a one-shot 1:1 similarity score.

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

Required: `user_image` (live capture) and `ref_image` (reference portrait). JPEG/PNG/WebP/TIFF, max 5 MB each.

curl example:
\```bash
curl -X POST 'https://verification.didit.me/v3/face-match/' \
-H 'x-api-key: YOUR_API_KEY' \
-F 'user_image=@./selfie.jpg' \
-F 'ref_image=@./id_portrait.jpg' \
-F 'save_api_request=true' \
-F 'vendor_data=user-123'
\```
Returns: { request_id, face_match: { status, score (0-100), user_image: {entities}, ref_image: {entities}, warnings: [...] } }. `status` is "Approved" when score > face_match_score_decline_threshold (default 30), else "Declined".

\# Status enum (per face_matches[].status / face_match.status)
"Not Started" | "In Progress" | "Approved" | "In Review" | "Declined" | "Abandoned" | "Kyc Expired"

\# Warnings (LogWarningChoices.FACEMATCH)
warnings[] risk codes include:
LOW_FACE_MATCH_SIMILARITY, NO_REFERENCE_IMAGE, NO_FACE_DETECTED, MULTIPLE_FACES_DETECTED.
Full catalogue: /core-technology/face-match/warnings-face-match.

\# Failure modes to handle
\- HTTP 403 — out of credits.
\- HTTP 400 — missing user_image or ref_image, file too large, unsupported extension.
\- status="Declined" with LOW_FACE_MATCH_SIMILARITY — the two faces do not match; do not approve.
\- NO_REFERENCE_IMAGE / NO_FACE_DETECTED — capture problems; ask the user to retry.

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

\</pre>



      
      

Paste into

![Resumen de los pasos de la verificación de identidad](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-verification-steps.png?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=42c64546f3495000d7ea3b10c4b5fa50)## Reintentos y comentarios accionablesEn una sesión de Didit, una coincidencia facial que falla por un **motivo de captura corregible** (el selfie es demasiado oscuro, está borroso o descentrado, o la similitud está en el límite) no se rechaza de inmediato. Se pide al usuario que **reintente con indicaciones**, hasta un número de intentos configurable, con el mismo modelo que la [prueba de vida](https://docs.didit.me/es/core-technology/liveness/overview.md).* **Presupuesto de intentos**: `face_match_max_attempts` controla el número total de envíos de coincidencia facial por sesión. El valor por defecto es **3** (un intento inicial más dos reintentos) y se puede configurar por nodo del flujo de verificación (rango 1-3).

* **Comentarios de reintento**: mientras queden intentos, un fallo reintentable mantiene al usuario en el paso y devuelve `feedback_codes` (los SDKs web y móviles los muestran automáticamente como mensajes de ayuda):

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **Agotamiento**: cuando se agota el presupuesto, se aplica el estado calculado (`Declined` o `In Review`).> [!NOTE]
>
> Los reintentos se aplican solo al **flujo de la sesión**. El endpoint independiente `POST /v3/face-match/` no guarda estado y es de un solo intento: devuelve la puntuación de similitud directamente, sin presupuesto de reintentos.## Cómo funciona**1. Captura inteligente**Empieza el proceso de verificación sin esfuerzo con nuestro sistema de captura intuitivo basado en IA.Los usuarios suben o fotografían sus documentos de identidad con asistencia en tiempo real:| Función | Descripción |
| - | - |
| **Detección automática** | Identifica automáticamente el tipo de documento y el país emisor |
| **Guía en tiempo real** | Indicaciones visuales para colocar, iluminar y enfocar correctamente |
| **Captura inteligente** | Captura automática cuando las condiciones son ideales, sin reintentos manuales |
| **Amplia compatibilidad** | Pasaportes, carnets de conducir, documentos nacionales de identidad y permisos de residencia |> [!NOTE]
>
> *Por qué importa*: nuestra captura inteligente reduce la fricción del usuario y garantiza envíos de alta calidad al primer intento, lo que aumenta la conversión y la confianza.**2. Procesamiento avanzado de datos**Extrae y valida los datos de identidad con una precisión inigualable.**Extracción de datos**: una tecnología de vanguardia procesa todos los campos clave:| Capacidad | Detalles |
| - | - |
| **Extracción de campos** | Nombre completo, fecha de nacimiento, número de documento, fechas de emisión y caducidad, nacionalidad y más |
| **OCR** | Reconocimiento óptico de caracteres de alta precisión para el texto |
| **Análisis de MRZ** | Análisis de la zona de lectura mecánica y decodificación de códigos de barras |**Validación de datos**:* Contrasta los datos entre las zonas visuales, la MRZ y los códigos de barras para comprobar su coherencia
* Coincidencia de formatos y patrones para detectar anomalías
* Consultas en tiempo real a bases de datos oficiales (donde esté permitido) para una verificación con garantías> [!NOTE]
>
> *Por qué importa*: el procesamiento exhaustivo de datos garantiza la precisión y elimina errores, para que confíes en cada verificación.**3. Análisis avanzado**Nuestro sistema basado en IA realiza comprobaciones exhaustivas:- Verificación de la autenticidad del documento
- Detección de manipulaciones y análisis de la integridad de la imagen
- Validación de elementos de seguridad (hologramas, marcas de agua, etc.)
- Comparación con plantillas de una base de datos certificadaLa **detección de vida del documento** previene el fraude mediante:| Tipo de ataque | Descripción |
| - | - |
| **Capturas de pantalla** | Documentos digitales fotografiados desde una pantalla |
| **Reproducción en pantalla** | Fotos de documentos mostrados en pantallas |
| **Copias impresas** | Reproducciones físicas de documentos originales |
| **Retratos alterados** | Documentos manipulados con fotos sustituidas o editadas |**4. Resultados e integración sin fricciones**Obtén información accionable al instante con opciones de entrega flexibles.**Resultados en tiempo real**:| Canal | Descripción |
| - | - |
| **Panel** | Actualizaciones inmediatas en un panel intuitivo |
| **Webhooks** | Notificaciones instantáneas por webhook para flujos automatizados |
| **API REST** | Integración sin fricciones con tus sistemas actuales |**Informes completos**:* Informes PDF detallados con los resultados de la verificación y las pruebas
* Pistas de auditoría para cumplimiento y conservación de registros
* Opciones personalizables para ajustarte a tus necesidades operativas> [!NOTE]
>
> *Por qué importa*: unos resultados rápidos y accesibles permiten a tu equipo actuar con agilidad, manteniendo un proceso seguro y auditable.***## Requisitos de los documentosPara que la verificación tenga éxito, los documentos deben cumplir estos estándares:#### Requisitos generales- Emitido por un gobierno y vigente dentro del periodo de validez configurado
- Físicamente intacto (sin daños, arañazos ni manchas que oculten detalles)
- Toda la información crítica (nombre completo, fecha de nacimiento, MRZ, etc.) claramente legible
- Datos coherentes en todos los documentos enviados#### Requisitos de la imagen- Foto original y en tiempo real (sin capturas de pantalla, escaneos ni copias digitales)
- Formatos admitidos: JPG, JPEG, PNG, PDF
- Tamaño máximo de archivo: 5MB
- Imagen a todo color con todas las esquinas del documento visibles
- Sin reflejos, sombras, edición digital ni manipulación
- Se exigen documentos físicos (los documentos de identidad digitales solo se admiten en regiones concretas donde están reconocidos oficialmente)## Ajustes adicionales por país y tipo de documentoConfigura reglas detalladas por país y tipo de documento directamente desde la consola. Estos controles te permiten adaptar los criterios de aceptación y las preferencias de transcripción a tus necesidades de cumplimiento.![Panel de ajustes avanzados de la coincidencia facial de Didit para los umbrales de similitud y las reglas de aceptación](https://mintcdn.com/didit-0f962782/z6T2GHM4Zh-iSj-K/images/id-additional-settings.jpeg?fit=max\&auto=format\&n=z6T2GHM4Zh-iSj-K\&q=85\&s=4238b10a404795a61926fbdf1a3adc20)* **Modo de caducidad**: elige cómo tratar los documentos con fecha de caducidad vencida.
  * **Rechazar documentos vencidos**: si la fecha de caducidad del documento es anterior a hoy, se marca como vencido y se rechaza.
  * **Permitir documentos vencidos**: no se marcan ni se bloquean los documentos con fecha de caducidad vencida.
* **Formato de caracteres preferido**: selecciona cómo deben normalizarse los nombres y campos extraídos.
  * **Preferir caracteres latinos (A–Z)**: ejemplo: "Mohammed"
  * **Preferir escritura original (no latina)**: ejemplo: "محمد"
* **Compatibilidad regional y subtipos**: activa documentos por región y especifica los subtipos aceptables cuando un tipo de documento tiene muchas variaciones.
  * Ejemplo: en los carnets de conducir de Estados Unidos, selecciona los subtipos exactos que aceptas (por ejemplo, Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, etc.).
  * Usa el control **Subtipos aceptados** para incluir o excluir rápidamente muchas variantes (por ejemplo, "128 selected").> Consejo: estos ajustes se aplican por país y tipo de documento, así que puedes ser estricto en unos mercados y más permisivo en otros.


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