Skip to main content
The Biometric Authentication report is how Didit reports back a returning-user re-verification. The workflow runs a fresh liveness check and, when Face Match is enabled in the workflow, a 1:1 face match against the portrait_image you supplied at session creation. Both checks appear as standard feature items in the V3 session decision response.
Didit biometric authentication report combining liveness check and face match against a stored portrait

​
Overview

Biometric Authentication is a workflow type (workflow_type: "biometric_authentication"), not a separate response object. When the workflow runs it emits:
  • One liveness check that captures a live selfie and scores it for spoofing.
  • One face match comparing the captured face against the portrait_image you passed at session creation (only when Face Match is enabled in the workflow).
portrait_image is a base64-encoded image, and it is required at session creation whenever the workflow includes Face Match — creating the session without it returns 400. Didit stores the portrait under the new session, so the face-match item’s source_image_session_id is set to that session’s own session_id (it tells you the reference came from the session’s stored portrait rather than from a document portrait, which would leave the field null).

​
Where it appears

Decision response keyPluralItem schema
liveness_checks[]One per liveness step (usually 1 in biometric auth)data-models#liveness-check
face_matches[]One per face-match step (null in liveness-only workflows)data-models#face-match
Both arrays are returned by GET /v3/session/{sessionId}/decision/ for sessions whose workflow type is biometric_authentication. They are always arrays — never singular objects — and each is null until its step has produced data. Each item carries a node_id so that multi-instance workflows can disambiguate steps.

​
Schema reference

The full field list is defined once on the data-models page so every report that surfaces these features shares one source of truth:
  • Liveness item schema — status, method, score, reference_image, video_url, age_estimation, matches[], face_quality, face_luminance, warnings[], node_id.
  • Face match item schema — status, score, source_image_session_id, source_image, target_image, warnings[], node_id.
  • Warning entry shape — feature, risk, additional_data, log_type, short_description, long_description, node_id.

​
Status values

Both liveness_checks[].status and face_matches[].status use the shared feature lifecycle (feature-level statuses):
StatusMeaning
Not FinishedThe step has not produced a final result yet (user has not completed it, or dropped off). Before a step starts at all, its array is simply null in the decision response.
ApprovedThe check passed all configured thresholds.
In ReviewThe score fell in the review band, or a configurable warning was set to review.
DeclinedThe score fell at or below the decline threshold, or an auto-decline warning fired (face attack, no face detected, face blocklisted, no reference image for face match).
Resub RequestedA reviewer asked the user to retry this step.
The overall session status aggregates both items: any feature in Declined declines the session, any in In Review puts the session in In Review, otherwise Approved (after every feature finishes). For threshold behavior and the full list of warning codes, see Biometric Authentication warnings.

​
Example — liveness + face match (approved)

Examples are abridged: the full decision envelope also carries session_url, metadata, callback, reviews, contact_details, expected_details, environment, created_at, and expires_at. 
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}

​
Example — liveness-only (Face Match disabled in the workflow)

{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": []
    }
  ],
  "face_matches": null
}
Liveness-only mode is a workflow configuration: when Face Match is disabled, portrait_image is not required at session creation and face_matches stays null. When Face Match is enabled, omitting portrait_image does not fall back to liveness-only — session creation fails with 400.

​
Example — face-match declined on low similarity

{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "error",
          "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"
        }
      ]
    }
  ]
}

​
Security note

reference_image, video_url, source_image, and target_image are signed URLs that expire after a limited validity window (4 hours by default). They point at biometric data — do not cache or surface them publicly. Store the verification result (status, score, source_image_session_id) on your side; re-fetch the decision endpoint if you need fresh URLs.

Biometric Auth warnings

Warning codes, thresholds, and automatic decline conditions.

Liveness report

Full field reference for liveness_checks[] items.

Face Match report

Full field reference for face_matches[] items.