> ## 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 coincidència facial 1:1: selfie i document

> Compara un selfie i el document amb Didit: puntuació de coincidència en sub-2s per a KYC i alta. Pagament per crida de $0.05 i $10 de franc/mes.

Didit Face Match compara dues cares 1:1, habitualment la selfie d'una prova de vida amb el retrat del document d'identitat de l'usuari, i retorna una puntuació de similitud de 0 a 100. Els llindars que configuris decideixen si la comprovació es supera; l'API independent `POST /v3/face-match/` rebutja per defecte una puntuació de 30 o inferior.A la lliçó de l'Academy sobre com interpretar el resultat d'una verificació, el capítol 6:16 tracta de la comprovació de coincidència facial dins d'una sessió real.[Face match — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

Prompt d'integració de coincidència facial
        Copia el prompt al porta-retalls



      
      

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



      
      

Enganxa a

![Visió general dels passos de verificació d'identitat](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)## Reintents i indicacions útilsEn una sessió de Didit, una coincidència facial que falla per un **motiu de captura solucionable** (la selfie és massa fosca, borrosa, descentrada o la similitud és al límit) no es rebutja immediatament. Es demana a l'usuari que **ho torni a intentar seguint les indicacions**, fins a un nombre configurable d'intents — el mateix model que s'utilitza per a la [Prova de vida](https://docs.didit.me/ca/core-technology/liveness/overview.md).* **Límit d'intents** — `face_match_max_attempts` controla el nombre total d'enviaments de coincidència facial per sessió. Per defecte són **3** (un intent inicial més dos reintents), configurable per a cada node del flux de treball (interval d'1 a 3).

* **Feedback de reintent** — mentre quedin intents, una fallada reintentable manté l'usuari en aquest pas i retorna `feedback_codes` (els SDK web i mòbil els mostren automàticament com a missatges d'orientació):

  ```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
  }
  ```

* **Exhauriment** — un cop exhaurit el límit, s'aplica l'estat calculat (`Declined` o `In Review`).> [!NOTE]
>
> Els reintents només s'apliquen al **flux de la sessió**. L'endpoint independent `POST /v3/face-match/` no té estat i només admet una execució: retorna directament la puntuació de similitud sense cap límit de reintents.## Com funciona**1. Captura intel·ligent**Comença el procés de verificació sense esforç amb el nostre sistema intuïtiu de captura basat en IA.Els usuaris pugen o fotografien els seus documents d'identitat amb assistència en temps real:| Característica | Descripció |
| - | - |
| **Detecció automàtica** | Identifica el tipus de document i el país emissor automàticament |
| **Guia en temps real** | Indicacions visuals per a un posicionament, il·luminació i enfocament òptims |
| **Captura intel·ligent** | Captura automàtica quan les condicions són ideals — sense necessitat de reintents manuals |
| **Àmplia compatibilitat** | Passaports, llicències de conduir, documents nacionals d'identitat i permisos de residència |> [!NOTE]
>
> *Per què és important*: la nostra captura intel·ligent redueix la fricció de l'usuari i assegura enviaments d'alta qualitat al primer intent, millorant les taxes de conversió i la confiança.**2. Processament avançat de dades**Extreu i valida dades d'identitat amb una precisió inigualable.**Extracció de dades** — La tecnologia d'última generació processa tots els camps clau:| Capacitat | Detalls |
| - | - |
| **Extracció de camps** | Nom complet, data de naixement, número de document, dates d'emissió/de caducitat, nacionalitat i més |
| **OCR** | Reconeixement òptic de caràcters d'alta precisió per al text |
| **Anàlisi de MRZ** | Anàlisi de la zona de lectura mecànica (MRZ) i descodificació de codis de barres |**Validació de dades**:* Contrasta les dades de les zones visuals, de la MRZ i dels codis de barres per garantir-ne la coherència
* Coincidència de formats i patrons per detectar anomalies
* Consultes en temps real a bases de dades governamentals (on estigui permès) per a una verificació fidedigna> [!NOTE]
>
> *Per què és important*: el processament exhaustiu de dades garanteix la precisió i elimina errors, oferint-te confiança en cada verificació.**3. Anàlisi avançada**El nostre sistema basat en IA realitza comprovacions exhaustives:- Verificació de l'autenticitat del document
- Detecció de manipulacions i anàlisi de la integritat de la imatge
- Validació d'elements de seguretat (hologrames, filigranes, etc.)
- Coincidència de plantilles amb una base de dades certificadaLa **prova de vida de documents** evita el frau causat per:| Tipus d'atac | Descripció |
| - | - |
| **Captures de pantalla** | Documents digitals fotografiats des d'una pantalla |
| **Reproducció en pantalla** | Fotos de documents mostrats en pantalles |
| **Còpies impreses** | Reproduccions físiques de documents originals |
| **Retrats alterats** | Documents manipulats amb fotos canviades o editades |**4. Resultats i integració fluids**Obtén informació útil per actuar a l'instant amb opcions de lliurament flexibles.**Resultats en temps real**:| Canal | Descripció |
| - | - |
| **Tauler** | Actualitzacions immediates mitjançant un tauler intuïtiu |
| **Webhooks** | Notificacions instantànies per webhook per a fluxos de treball automatitzats |
| **API REST** | Integració fluida amb els teus sistemes existents |**Informes exhaustius**:* Informes detallats en PDF amb resultats de la verificació i proves
* Registres d'auditoria per al compliment i la conservació de registres
* Opcions personalitzables per adaptar-se a les teves necessitats operatives> [!NOTE]
>
> *Per què és important*: uns resultats ràpids i accessibles permeten al teu equip actuar ràpidament mantenint un procés segur i auditable.***## Requisits dels documentsPer obtenir resultats òptims en la verificació, els documents han de complir aquests estàndards:#### Requisits generals- Emès pel govern i vàlid dins del seu període de validesa configurat
- Físicament intacte (sense danys, rascades o taques que n'ocultin els detalls)
- Tota la informació crítica (nom complet, data de naixement, MRZ, etc.) clarament llegible
- Dades coherents en tots els documents enviats#### Requisits de les imatges- Foto original en temps real (sense captures de pantalla, escanejos ni còpies digitals)
- Formats admesos: JPG, JPEG, PNG, PDF
- Mida màxima de fitxer: 5MB
- Imatge en color amb totes les cantonades del document visibles
- Sense reflexos, ombres, edició digital o manipulació
- Es requereixen documents físics (els documents d'identitat digitals només s'admeten en regions seleccionades on estiguin reconeguts oficialment)## Configuració addicional per país i tipus de documentConfigura regles detallades per país i tipus de document directament des de la consola. Aquests controls et permeten adaptar els criteris d'acceptació i les preferències de transcripció a les teves necessitats de compliment normatiu.![Panell de configuració avançada de coincidència facial de Didit per a llindars de similitud i regles d'acceptació](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)* **Mode de caducitat**: Tria com gestionar els documents amb dates de caducitat superades.
  * **Rebutjar caducats**: Si la data de caducitat del document és anterior a avui, marca'l com a caducat i rebutja'l.
  * **Permetre caducats**: No marquis ni bloquegis documents amb una data de caducitat superada.
* **Format de caràcters preferit**: Selecciona com s'han de normalitzar els noms i els camps extrets.
  * **Preferir caràcters llatins (A–Z)**: Exemple: "Mohammed"
  * **Preferir el sistema d'escriptura original (no llatí)**: Exemple: "محمد"
* **Suport regional i subtipus**: Habilita documents per regió i especifica els subtipus acceptables quan un tipus de document contingui moltes variacions.
  * Exemple: Per als permisos de conduir dels Estats Units, selecciona els subtipus exactes que acceptes (p. ex., Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, etc.).
  * Utilitza el control "Accepted subtypes" per incloure o excloure ràpidament moltes variants (p. ex., "128 selected").> Consell: Aquesta configuració s'aplica per país i tipus de document, de manera que pots ser estricte en alguns mercats i més permissiu en d'altres.


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