Correspondance faciale : score de similarité en JSON

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 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 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.
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.
API autonome de correspondance faciale — pour les comparaisons directes 1:1, voir API autonome de correspondance faciale.

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

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

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

En cours d’examen — similarité limite

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/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

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/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 — énumération complète des avertissements, causes et mesures correctives.
Rapport de détection du vivant — l’étape en amont qui capture l’image cible.
Webhooks — écoutez session.status.updated pour recevoir le rapport.
Modèles de données — Correspondance faciale — schéma canonique comprenant tous les champs.

Authentification

Vérification

Surveillance

Plateforme

Correspondance faciale : score de similarité en JSON

Vue d’ensemble

Où il apparaît dans les réponses de l’API

Schéma

Valeurs de statut

Exemples

Approuvé — correspondance nette

En cours d’examen — similarité limite

Refusé — aucune image de référence pour la comparaison

Note de sécurité

Ressources associées

​Vue d’ensemble

​Où il apparaît dans les réponses de l’API

​Schéma

​Valeurs de statut

​Exemples

​Approuvé — correspondance nette

​En cours d’examen — similarité limite

​Refusé — aucune image de référence pour la comparaison

​Note de sécurité

​Ressources associées

Vue d’ensemble

Où il apparaît dans les réponses de l’API

Schéma

Valeurs de statut

Exemples

Approuvé — correspondance nette

En cours d’examen — similarité limite

Refusé — aucune image de référence pour la comparaison

Note de sécurité

Ressources associées