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

# Correspondance faciale 1:1 : API selfie et ID

> Comparez selfie et pièce d'identité avec Didit : reconnaissance faciale IA, score en moins de 2s, $0.05 par appel et $10 gratuits/mois pour le KYC.

Didit Face Match compare deux visages en 1:1, généralement le selfie issu d'un contrôle de détection du vivant au portrait figurant sur le document d'identité de l'utilisateur, et renvoie un score de similarité de 0 à 100. Les seuils que vous définissez déterminent si le contrôle est validé ; l'API autonome `POST /v3/face-match/` refuse par défaut un score inférieur ou égal à 30.Dans le cours Didit Academy sur la lecture d'un résultat de vérification, le chapitre 6:16 aborde le contrôle de correspondance faciale au sein d'une session réelle.[Face match — Didit Academy](https://www.youtube.com/embed/7htTWCWsl60?start=376\&rel=0\&playsinline=1)

Prompt d'intégration de la correspondance faciale
        Copier le prompt dans le presse-papiers



      
      

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



      
      

Coller dans

![Aperçu des étapes de vérification d'identité](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)## Nouvelles tentatives et retours exploitablesAu cours d'une session Didit, une correspondance faciale qui échoue pour une **raison de capture rectifiable** (le selfie est trop sombre, flou, décentré, ou la similarité est limite) n'est pas immédiatement refusée. L'utilisateur est invité à **réessayer avec des conseils**, dans la limite d'un nombre configurable de tentatives — selon le même modèle que celui utilisé pour la [Détection du vivant](https://docs.didit.me/fr/core-technology/liveness/overview.md).* **Budget de tentatives** — `face_match_max_attempts` contrôle le nombre total de soumissions de correspondance faciale par session. Par défaut **3** (une tentative initiale plus deux nouvelles tentatives), configurable par nœud de workflow (plage de 1 à 3).

* **Retour lors d'une nouvelle tentative** — tant qu'il reste des tentatives, un échec rectifiable maintient l'utilisateur sur l'étape et renvoie `feedback_codes` (les SDK Web et Mobile affichent automatiquement ces éléments sous forme de messages de guidage) :

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

* **Épuisement** — une fois le budget épuisé, le statut calculé est appliqué (`Declined` ou `In Review`).> [!NOTE]
>
> Les nouvelles tentatives s'appliquent uniquement au **parcours de session**. L'endpoint autonome `POST /v3/face-match/` est sans état et à usage unique — il renvoie directement le score de similarité sans budget de nouvelles tentatives.## Fonctionnement**1. Capture intelligente**Initiez sans effort le processus de vérification grâce à notre système de capture intuitif basé sur l'IA.Les utilisateurs téléversent ou prennent en photo leurs documents d'identité avec une assistance en temps réel :| Fonctionnalité | Description |
| - | - |
| **Détection automatique** | Identifie automatiquement le type de document et le pays de délivrance |
| **Guidage en temps réel** | Repères visuels pour un positionnement, un éclairage et une mise au point optimaux |
| **Capture intelligente** | Capture automatique lorsque les conditions sont idéales — aucune nouvelle tentative manuelle requise |
| **Large prise en charge** | Passeports, permis de conduire, cartes nationales d'identité et titres de séjour |> [!NOTE]
>
> *Pourquoi c'est important* : notre capture intelligente réduit les frictions pour l'utilisateur et garantit des soumissions de haute qualité dès la première tentative, améliorant ainsi les taux de conversion et la confiance.**2. Traitement avancé des données**Extrayez et validez les données d'identité avec une précision inégalée.**Extraction de données** — Une technologie de pointe traite tous les champs clés :| Capacité | Détails |
| - | - |
| **Extraction de champs** | Nom complet, date de naissance, numéro de document, dates de délivrance et d'expiration, nationalité, etc. |
| **OCR** | Reconnaissance optique de caractères de haute précision pour le texte |
| **Analyse MRZ** | Analyse de la zone de lecture optique (MRZ) et décodage des codes-barres |**Validation des données** :* Recoupe les données entre les zones visuelles, la MRZ et les codes-barres pour en vérifier la cohérence
* Analyse des formats et des motifs pour détecter les anomalies
* Requêtes en temps réel auprès des bases de données gouvernementales (lorsque cela est autorisé) pour une vérification faisant autorité> [!NOTE]
>
> *Pourquoi c'est important* : un traitement complet des données garantit l'exactitude et élimine les erreurs, vous donnant toute confiance dans chaque vérification.**3. Analyse avancée**Notre système alimenté par l'IA effectue des contrôles exhaustifs :- Vérification de l'authenticité du document
- Détection des altérations et analyse de l'intégrité de l'image
- Validation des éléments de sécurité (hologrammes, filigranes, etc.)
- Comparaison du modèle avec une base de données certifiéeLa **détection du vivant** des documents prévient la fraude liée à :| Type d'attaque | Description |
| - | - |
| **Captures d'écran** | Documents numériques photographiés depuis un écran |
| **Rejeu sur écran** | Photos de documents affichés sur des écrans |
| **Copies imprimées** | Reproductions physiques de documents originaux |
| **Portraits altérés** | Documents manipulés avec des photos remplacées ou retouchées |**4. Résultats et intégration fluides**Obtenez instantanément des informations exploitables grâce à des options de livraison flexibles.**Résultats en temps réel** :| Canal | Description |
| - | - |
| **Tableau de bord** | Mises à jour immédiates via un tableau de bord intuitif |
| **Webhooks** | Notifications webhook instantanées pour des workflows automatisés |
| **API REST** | Intégration fluide dans vos systèmes existants |**Rapports complets** :* Rapports PDF détaillés avec les résultats de vérification et les éléments de preuve
* Journaux d'audit pour la conformité et la tenue de registres
* Options personnalisables pour répondre à vos besoins opérationnels> [!NOTE]
>
> *Pourquoi c'est important* : des résultats rapides et accessibles permettent à votre équipe d'agir vite tout en maintenant un processus sécurisé et auditable.***## Exigences relatives aux documentsPour optimiser les chances de réussite de la vérification, les documents doivent respecter ces critères :#### Exigences générales- Délivré par un gouvernement et valide au cours de sa période de validité configurée
- Physiquement intact (aucun dommage, rayure ou tache ne masquant les détails)
- Toutes les informations essentielles (nom complet, date de naissance, MRZ, etc.) doivent être clairement lisibles
- Données cohérentes sur l'ensemble des documents soumis#### Exigences relatives aux images- Photo originale prise en temps réel (pas de captures d'écran, de scans ou de copies numériques)
- Formats pris en charge : JPG, JPEG, PNG, PDF
- Taille maximale du fichier : 5MB
- Image en couleur avec tous les coins du document visibles
- Sans reflet, ombre, retouche numérique ou manipulation
- Documents physiques requis (pièces d'identité numériques prises en charge uniquement dans certaines régions où elles sont officiellement reconnues)## Paramètres supplémentaires par pays et type de documentConfigurez des règles précises par pays et type de document directement depuis la console. Ces contrôles vous permettent d'adapter les critères d'acceptation et les préférences de transcription à vos exigences de conformité.![Panneau de paramètres avancés de correspondance faciale de Didit pour les seuils de similarité et les règles d'acceptation](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 d'expiration** : Choisissez comment traiter les documents dont la date d'expiration est dépassée.
  * **Refuser les documents expirés** : Si la date d'expiration du document est antérieure à aujourd'hui, marquez-le comme expiré et refusez-le.
  * **Autoriser les documents expirés** : Ne signalez ni ne bloquez les documents dont la date d'expiration est dépassée.
* **Format de caractères préféré** : Sélectionnez le mode de normalisation des noms et des champs extraits.
  * **Privilégier les caractères latins (A–Z)** : Exemple : "Mohammed"
  * **Privilégier le système d'écriture d'origine (non latin)** : Exemple : "محمد"
* **Prise en charge régionale et sous-types** : Activez les documents par région et spécifiez les sous-types acceptables lorsqu'un type de document comporte de nombreuses variantes.
  * Exemple : Pour les permis de conduire des États-Unis, sélectionnez les sous-types exacts que vous acceptez (par ex., Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, etc.).
  * Utilisez le contrôle "Sous-types acceptés" pour inclure ou exclure rapidement de nombreuses variantes (par ex., "128 sélectionnés").> Conseil : Ces paramètres s'appliquent par pays et type de document, ce qui vous permet d'être strict sur certains marchés tout en étant plus permissif sur d'autres.


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