Détection du vivant : score, méthode et correspondances

Aperçu

Le rapport de détection du vivant consigne tout ce que Didit a observé en vérifiant qu’une personne réelle et vivante se trouvait devant la caméra — et non une photo imprimée, une reproduction sur écran ou un deepfake. Il comprend la méthode de détection du vivant, un score de confiance de 0 à 100, le selfie de référence et la vidéo de capture, une estimation de l’âge facultative, des métriques de qualité de détection du vivant passive, ainsi que des correspondances faciales inter-sessions avec l’historique et la liste de blocage de votre application. Le rapport est généré une fois que l’utilisateur a terminé l’étape de détection du vivant dans un workflow (ou après un appel direct à l’endpoint autonome de détection faciale). Didit exécute l’une des trois méthodes de détection du vivant (3D active, avec flash ou passive), note la capture, recherche les schémas d’usurpation connus et compare biométriquement le visage à tous les autres visages déjà observés dans votre application. Chaque rapport possède son propre status — indépendant du statut global de la session — qui reflète le résultat de l’étape de détection du vivant seule :

Approuvé — visage détecté, score de détection du vivant supérieur au seuil d’examen, aucun avertissement de refus automatique déclenché.
En cours d’examen — un ou plusieurs avertissements configurés pour examen ont été déclenchés, ou le score est inférieur ou égal au seuil d’examen mais au-dessus du seuil de refus.
Refusé — une condition de refus automatique s’est déclenchée (NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST ou les risques liés à l’âge sur les flux d’estimation de l’âge), un avertissement configurable a été orienté vers un refus, ou le score est inférieur ou égal au seuil de refus.
Non terminé — l’utilisateur n’a jamais terminé l’étape de détection du vivant.

Emplacement dans les réponses d’API

Le rapport de détection du vivant apparaît sous la forme liveness_checks[] dans GET /v3/session/{sessionId}/decision/ — toujours un tableau JSON, jamais un objet liveness unique. Plusieurs entrées s’affichent lorsqu’un workflow exécute la détection du vivant plus d’une fois (par exemple une vérification principale suivie d’une nouvelle capture).

API de décision de session — GET /v3/session/{sessionId}/decision/ renvoie liveness_checks[] au niveau racine. Voir Récupérer la décision de session.
Webhooks — les payloads session.status.updated incluent le même tableau liveness_checks[] dès que l’étape a produit des données. Voir Webhooks.
API autonome de détection du vivant — voir API autonome de détection du vivant.

Lisez response.liveness_checks[0] et parcourez le tableau — la structure liveness 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 reproduisent ce schéma canonique.

Champ	Type	Description
`status`	`"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"`	Statut de l’étape de détection du vivant (voir ci-dessous).
`node_id`	string \| null	Nœud du graphe de workflow ayant produit ce rapport.
`method`	`"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"`	Méthode de détection du vivant ayant produit cette capture.
`score`	number 0–100 \| null	Score de confiance de détection du vivant, arrondi à 2 décimales.
`reference_image`	string (URL signée) \| null	Selfie de référence extrait de la capture. URL signée avec une fenêtre de validité limitée.
`video_url`	string (URL signée) \| null	Vidéo complète de capture de détection du vivant (méthodes actives). URL signée avec une fenêtre de validité limitée.
`age_estimation`	number \| null	Âge estimé en années du plus grand visage dans l’image de référence.
`face_quality`	number 0–100 \| null	Qualité du visage en détection du vivant passive, normalisée en pourcentage. Renseigné uniquement lorsque `method = "PASSIVE"`.
`face_luminance`	number 0–100 \| null	Luminance faciale en détection du vivant passive, normalisée de 0–255 en pourcentage. Renseigné uniquement lorsque `method = "PASSIVE"`.
`matches[]`	array	Correspondances faciales inter-sessions (voir ci-dessous).
`warnings[]`	array	Avertissements au niveau du module — voir Avertissements de détection du vivant. Chaque entrée suit la structure de l’Objet avertissement (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`).

Correspondances faciales inter-sessions

matches[] liste les visages dans l’historique de votre application ayant dépassé le seuil de similarité biométrique par rapport à ce selfie — jusqu’à 5 entrées, les visages sur liste de blocage et sur liste autorisée en premier, puis par similarité décroissante. Les candidats éligibles sont les visages sur liste de blocage, les visages sur liste autorisée, les visages issus de sessions Approved et les visages importés pour vos utilisateurs fournisseurs. Les visages appartenant au même utilisateur (même vendor_data, ou même utilisateur fournisseur lorsque disponible) sont exclus de l’intégralité de la recherche — à la fois pour la détection de doublons et le filtrage sur liste de blocage. Chaque entrée comprend :

Champ	Type	Description
`session_id`	string (UUID) \| null	Session correspondante. `null` lorsque `source` est `imported` ou `list_entry`.
`session_number`	number \| null	Numéro séquentiel de session pour la session correspondante. `null` pour les sources autres que des sessions.
`similarity_percentage`	number 0–100	Score de similarité biométrique, borné entre 0 et 100.
`vendor_data`	string \| null	Vos données de référence issues de la session correspondante (ou de l’utilisateur fournisseur, pour les visages importés).
`verification_date`	string (ISO 8601) \| null	Date de création de la session correspondante (ou du visage importé).
`user_details`	object \| null	`{ full_name, document_type, document_number }` issus du KYC de la session correspondante. Les visages importés renseignent uniquement `full_name` (les deux champs de document sont `null`) ; `null` lorsqu’aucun détail n’est enregistré.
`match_image_url`	string (URL signée) \| null	Visage de référence issu de la session correspondante, du visage importé ou de l’entrée de liste.
`status`	string \| null	Statut de la session correspondante (par exemple `"Approved"`). `null` pour les sources autres que des sessions.
`is_blocklisted`	boolean	`true` lorsque le visage correspondant figure sur votre liste de blocage de visages.
`is_allowlisted`	boolean	`true` lorsque le visage correspondant figure sur votre liste autorisée de visages (les actions liées aux doublons de visages sont ignorées).
`api_service`	string \| null	Défini lorsque le visage correspondant provient d’un appel d’API autonome (par exemple `"PASSIVE_LIVENESS"`) ; `null` pour les sessions de workflow et les sources autres que des sessions.
`source`	`"session" \| "imported" \| "list_entry"`	Provenance du visage correspondant : une autre session de vérification, un visage téléversé pour un utilisateur fournisseur ou un visage d’une liste autorisée/de blocage gérée par l’organisation.

Valeurs de statut

Les statuts proviennent de l’enum partagé des statuts de fonctionnalités (FeatureStatusChoices).

Statut	Signification	Effet en aval
`Approved`	Visage détecté, score de détection du vivant supérieur au seuil d’examen, aucun avertissement de refus automatique déclenché.	Comptabilisé comme une vérification de détection du vivant réussie.
`In Review`	Score inférieur ou égal au seuil d’examen mais supérieur au seuil de refus, ou un avertissement orienté vers l’examen a été déclenché.	La session passe également à `In Review` jusqu’à l’intervention d’un réviseur.
`Declined`	Un risque de refus automatique s’est déclenché (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, ou les risques d’âge sur les flux d’estimation de l’âge), un avertissement configurable a été orienté vers le refus, ou le score est inférieur ou égal au seuil de refus.	La session est refusée à moins qu’une autre branche approuvée ne satisfasse le workflow.
`Not Finished`	L’utilisateur a abandonné l’étape de détection du vivant (ou un échec de capture réessayable est en attente d’une nouvelle tentative).	La branche de détection du vivant n’a pas produit de résultat.
`Resub Requested`	Un réviseur a demandé une nouvelle soumission de cette étape depuis la console.	Temporaire — remplacé dès que l’utilisateur effectue une nouvelle capture.

Exemples

Approved — capture active-3D propre, sans problème

{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}

In Review — détection du vivant passive, capture de faible qualité et doublon potentiel

{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}

Ici, la qualité du visage (12.4) se situe en dessous du seuil d’examen par défaut (15), la luminance (18.7) se situe en dessous du minimum par défaut (20), et l’action pour visage en doublon du workflow est définie sur Review — ainsi, les trois avertissements portent log_type: "warning" et le rapport passe à l’état In Review.

Note de sécurité

Les vidéos de détection du vivant et les selfies constituent des données biométriques — les URL signées sont temporaires et expirent (après 4 heures par défaut). 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, score et des avertissements — conservez le strict minimum pour limiter les données biométriques sur vos serveurs.

Voir aussi

Avertissements de détection du vivant — énumération complète des avertissements, causes et mesures correctives.
Webhooks — écoutez session.status.updated pour recevoir le rapport.
Modèles de données — Détection du vivant — schéma canonique avec tous les champs.
Rapport de correspondance faciale — la correspondance faciale 1:1 effectuée par rapport au portrait du document.

Authentification

Vérification

Surveillance

Plateforme

Détection du vivant : score, méthode et correspondances

Aperçu

Emplacement dans les réponses d’API

Schéma

Correspondances faciales inter-sessions

Valeurs de statut

Exemples

Approved — capture active-3D propre, sans problème

In Review — détection du vivant passive, capture de faible qualité et doublon potentiel

Note de sécurité

Voir aussi

​Aperçu

​Emplacement dans les réponses d’API

​Schéma

​Correspondances faciales inter-sessions

​Valeurs de statut

​Exemples

​Approved — capture active-3D propre, sans problème

​In Review — détection du vivant passive, capture de faible qualité et doublon potentiel

​Note de sécurité

​Voir aussi

Aperçu

Emplacement dans les réponses d’API

Schéma

Correspondances faciales inter-sessions

Valeurs de statut

Exemples

Approved — capture active-3D propre, sans problème

In Review — détection du vivant passive, capture de faible qualité et doublon potentiel

Note de sécurité

Voir aussi