Biometric Authentication Report

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 reference face resolved at session creation (the portrait_image you supplied, or the user’s stored face looked up by vendor_data). 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 reference face resolved at session creation (only when Face Match is enabled in the workflow).

Whenever the workflow includes Face Match, session creation needs a reference face. Send portrait_image (base64-encoded image, max 2MB), or omit it and Didit reuses the face already stored for the vendor_data user: an approved liveness face first, then the ePassport chip photo, then the ID document portrait, then a manually enrolled profile face. If neither portrait_image nor a stored face is available, session creation returns 400 with

{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}

. In both cases the resolved reference is recorded 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 captured in the same session, which would leave the field null).

Where it appears

Decision response key	Plural	Item 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):

Status	Meaning
`Not Finished`	The 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.
`Approved`	The check passed all configured thresholds.
`In Review`	The score fell in the review band, or a configurable warning was set to review.
`Declined`	The 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 Requested`	A 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, no reference face is needed at session creation and face_matches stays null. When Face Match is enabled, omitting portrait_image does not fall back to liveness-only: Didit reuses the face stored for the vendor_data user, and if no stored face exists 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.

Authentication

Verification

Monitoring

Platform

Overview

Where it appears

Schema reference

Status values

Example — liveness + face match (approved)

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

Example — face-match declined on low similarity

Security note

Biometric Auth warnings

Liveness report

Face Match report

​Overview

​Where it appears

​Schema reference

​Status values

​Example — liveness + face match (approved)

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

​Example — face-match declined on low similarity

​Security note

​Related

Biometric Auth warnings

Liveness report

Face Match report

Overview

Where it appears

Schema reference

Status values

Example — liveness + face match (approved)

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

Example — face-match declined on low similarity

Security note

Related