> ## 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 : score de similarité en JSON > Analysez le rapport 1:1 de correspondance faciale Didit : statut, score de similarité, URL d'images, avertissements et données de l'API. ## Vue d'ensemble Le **rapport de correspondance faciale** restitue une comparaison biométrique 1:1 entre le selfie en direct capturé pendant la détection du vivant et une image de référence — le plus souvent le portrait extrait de la pièce d'identité. Il renvoie un score de similarité unique compris entre 0 et 100, des URL signées pour les deux images comparées, la session source de l'image de référence, ainsi que les avertissements générés par la correspondance. Le rapport est généré une fois que l'utilisateur a terminé à la fois l'étape de détection du vivant et l'étape documentaire dans un workflow (ou, pour les workflows basés sur le portrait comme l'authentification biométrique, après la seule détection du vivant), ou directement via l'[API de correspondance faciale](https://docs.didit.me/fr/standalone-apis/face-match.md) autonome lorsque vous fournissez vous-même deux images faciales arbitraires. Chaque rapport comporte son propre `status` — indépendant du statut global de la session — qui reflète l'issue de la seule étape de correspondance faciale : * **Approuvé** — le `score` est supérieur au seuil d'examen et aucun avertissement de refus automatique ne s'est déclenché. * **En cours d'examen** — le `score` se situe entre les seuils de refus et d'examen, ou aucun score n'a pu être calculé et `face_match_not_computed_action` est défini sur `REVIEW`. * **Refusé** — le `score` est inférieur ou égal au seuil de refus, `NO_REFERENCE_IMAGE` s'est déclenché, ou aucun score n'a pu être calculé et `face_match_not_computed_action` est défini sur `DECLINE`. * **Nouvelle soumission demandée** — un réviseur a demandé à l'utilisateur de soumettre à nouveau cette étape depuis la console. * **Non terminée** — l'étape de correspondance faciale n'a pas encore produit de résultat (y compris pendant que l'utilisateur réessaie une capture ayant échoué). ## Où il apparaît dans les réponses de l'API Le rapport de correspondance faciale est transmis au sein du tableau `face_matches[]` — **toujours un tableau JSON**, jamais un objet `face_match` unique. Il est `null` jusqu'à ce qu'au moins une étape de correspondance faciale ait produit des données, et plusieurs entrées apparaissent lorsqu'un workflow exécute la correspondance faciale plusieurs fois. Un workflow d'[Adaptive Age Verification](https://docs.didit.me/fr/core-technology/age-estimation/overview.md#estimation-adaptative-de-l’âge) le remplit également lorsque la solution de repli de vérification d'identité est exécutée : cette entrée indique le nœud d'estimation de l'âge comme son `node_id`, puisque le workflow ne possède pas de nœud de correspondance faciale propre. * **API de décision de session** — `GET /v3/session/{sessionId}/decision/` renvoie `face_matches[]` au niveau racine. Voir [Récupérer la décision de session](https://docs.didit.me/fr/sessions-api/retrieve-session.md). * **Webhooks** — les payloads `session.status.updated` incluent le même tableau `face_matches[]` une fois que l'étape a produit des données. Voir [Webhooks](https://docs.didit.me/fr/integration/webhooks.md). * **API autonome de correspondance faciale** — pour les comparaisons directes 1:1, voir [API autonome de correspondance faciale](https://docs.didit.me/fr/standalone-apis/face-match.md). > [!NOTE] > > Lisez `response.face_matches[0]` et itérez sur le tableau — la structure `face_match` au singulier mentionnée dans certains tutoriels plus anciens n'existe pas sur l'endpoint de décision v3. ## Schéma Le schéma canonique champ par champ se trouve sur la page de référence [Modèles de données](https://docs.didit.me/fr/reference/data-models.md#correspondance-faciale). Les champs ci-dessous reflètent ce schéma canonique. | Champ | Type | Description | | - | - | - | | `status` | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | Statut de l'étape de correspondance faciale (`FeatureStatusChoices`). | | `node_id` | string \| null | Nœud du graphe de workflow ayant produit ce rapport. | | `score` | number 0–100 \| null | Score de similarité biométrique, arrondi à 2 décimales. `null` lorsqu'aucune comparaison n'a été possible. | | `source_image_session_id` | string \| null | UUID de la session dont le portrait stocké a fourni l'image de référence (source) — défini dans les flux basés sur un portrait (authentification biométrique ou portrait fourni à la création de la session). `null` lorsque l'image de référence est le portrait du document capturé au cours de la même session. | | `source_image` | string (URL signée) | L'image de référence (généralement le portrait du document). URL signée à courte durée de vie — téléchargez-la rapidement, ne persistez jamais l'URL. | | `target_image` | string (URL signée) | L'image cible (généralement le selfie de détection du vivant). URL signée à courte durée de vie — téléchargez-la rapidement, ne persistez jamais l'URL. | | `warnings[]` | array | Avertissements au niveau du module. Chaque entrée comprend `feature` (toujours `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description` et `node_id` — voir [Avertissements de correspondance faciale](https://docs.didit.me/fr/core-technology/face-match/warnings-face-match.md). | ## Valeurs de statut | Statut | Signification | Effet en aval | | - | - | - | | `Approved` | Score supérieur au seuil d'examen et aucun avertissement de refus automatique ne s'est déclenché. | Compte comme une correspondance faciale réussie. | | `In Review` | Score supérieur au seuil de refus mais inférieur ou égal au seuil d'examen, ou aucun score n'a pu être calculé (`FACE_MATCH_NOT_COMPUTED`, par exemple après une recherche sans document n'ayant laissé aucune référence) avec `face_match_not_computed_action` défini sur `REVIEW`. | La session passe également à `In Review` jusqu'à ce qu'un réviseur intervienne. | | `Declined` | Score inférieur ou égal au seuil de refus, `NO_REFERENCE_IMAGE` s'est déclenché, ou aucun score n'a pu être calculé avec `face_match_not_computed_action` défini sur `DECLINE`. | La session est refusée à moins qu'une autre branche approuvée ne satisfasse le workflow. | | `Resub Requested` | Un réviseur a demandé une nouvelle soumission de cette étape depuis la console. | L'utilisateur est invité à effectuer une nouvelle capture. | | `Not Finished` | L'étape de correspondance faciale n'a pas produit de résultat (une entrée était manquante, le workflow n'a jamais atteint l'étape de comparaison ou l'utilisateur est toujours dans la boucle de réessai de capture). | La branche ne s'est pas terminée. | Les échecs dus à une faible similarité font l'objet d'une nouvelle tentative avant que le statut ne soit figé : l'utilisateur bénéficie d'un maximum de `face_match_max_attempts` captures (3 par défaut), et seul le score de la dernière tentative est appliqué. Des règles de statut personnalisées configurées sur le nœud de workflow peuvent également ajuster le statut résultant, en se combinant avec le statut dérivé du score selon l'ordre de priorité `Declined` > `In Review` > `Approved`. ## Exemples ### Approuvé — correspondance nette ```json theme={null} { "face_matches": [ { "status": "Approved", "node_id": "feature_face_match_1", "score": 96.42, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [] } ] } ``` ### En cours d'examen — similarité limite ```json theme={null} { "face_matches": [ { "status": "In Review", "node_id": "feature_face_match_1", "score": 65.43, "source_image_session_id": null, "source_image": "https:///source-image.jpg", "target_image": "https:///target-image.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "LOW_FACE_MATCH_SIMILARITY", "additional_data": null, "log_type": "warning", "short_description": "Low face match similarity", "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.", "node_id": "feature_face_match_1" } ] } ] } ``` ### Refusé — aucune image de référence pour la comparaison ```json theme={null} { "face_matches": [ { "status": "Declined", "node_id": "feature_face_match_1", "score": null, "source_image_session_id": null, "source_image": null, "target_image": "https:///target-image.jpg", "warnings": [ { "feature": "FACEMATCH", "risk": "NO_REFERENCE_IMAGE", "additional_data": null, "log_type": "error", "short_description": "No source image found for performing face match", "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.", "node_id": "feature_face_match_1" } ] } ] } ``` ## Note de sécurité Les URL signées pour `source_image` et `target_image` constituent des données biométriques et expirent après une courte fenêtre de validité. Considérez-les comme éphémères : ne les mettez pas en cache et ne les exposez pas publiquement. En règle générale, votre application n'a besoin que de `status` et de `score` — stockez le moins d'informations possible afin de minimiser les données biométriques présentes sur vos serveurs. ## Ressources associées * [Avertissements de correspondance faciale](https://docs.didit.me/fr/core-technology/face-match/warnings-face-match.md) — énumération complète des avertissements, causes et mesures correctives. * [Rapport de détection du vivant](https://docs.didit.me/fr/core-technology/liveness/report-liveness.md) — l'étape en amont qui capture l'image cible. * [Webhooks](https://docs.didit.me/fr/integration/webhooks.md) — écoutez `session.status.updated` pour recevoir le rapport. * [Modèles de données — Correspondance faciale](https://docs.didit.me/fr/reference/data-models.md#correspondance-faciale) — schéma canonique comprenant tous les champs. This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.