Liveness report

Overview

The liveness report captures everything Didit observed while verifying that a real, live person was in front of the camera — not a printed photo, screen replay, or deepfake. It includes the liveness method, a 0–100 confidence score, the reference selfie and capture video, an optional age estimate, passive-liveness quality metrics, and cross-session face matches against your application’s history and blocklist. The report is produced after the user completes the liveness step in a workflow (or hits the standalone face endpoint). Didit runs one of three liveness methods (active 3D, flashing, or passive), scores the capture, screens for known spoof patterns, and compares the face biometrically against every other face you’ve seen in your application. Each report carries its own status — independent of the overall session status — that reflects how the liveness step alone resolved:

Approved — face detected, liveness score above the review threshold, no auto-decline warning fired.
In Review — one or more warnings routed to review fired, or the score is at or below the review threshold but above the decline threshold.
Declined — an auto-decline condition fired (NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST, or the age risks on age-estimation flows), a configurable warning was routed to decline, or the score is at or below the decline threshold.
Not Finished — the user never completed the liveness step.

Where it appears in API responses

The liveness report appears as liveness_checks[] in GET /v3/session/{sessionId}/decision/ — always a JSON array, never a singular liveness object. Multiple entries appear when a workflow runs liveness more than once (for example a primary check plus a re-capture).

Session decision API — GET /v3/session/{sessionId}/decision/ returns liveness_checks[] at the top level. See Retrieve session decision.
Webhooks — session.status.updated payloads include the same liveness_checks[] array once the step has produced data. See Webhooks.
Standalone liveness API — see Liveness standalone API.

Read response.liveness_checks[0] and iterate the array — the singular liveness shape some older tutorials referenced does not exist on the v3 decision endpoint.

Schema

The canonical field-by-field schema lives on the Data models reference page. The fields below mirror that canonical schema.

Field	Type	Description
`status`	`"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"`	Liveness-step status (see below).
`node_id`	string \| null	Workflow graph node that produced this report.
`method`	`"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"`	The liveness method that produced this capture.
`score`	number 0–100 \| null	Liveness confidence score, rounded to 2 decimals.
`reference_image`	string (signed URL) \| null	Reference selfie extracted from the capture. Signed URL with a limited validity window.
`video_url`	string (signed URL) \| null	Full liveness capture video (active methods). Signed URL with a limited validity window.
`age_estimation`	number \| null	Estimated age in years of the largest face in the reference image.
`face_quality`	number 0–100 \| null	Passive-liveness face quality, normalized to a percentage. Populated only when `method = "PASSIVE"`.
`face_luminance`	number 0–100 \| null	Passive-liveness facial luminance, normalized from 0–255 to a percentage. Populated only when `method = "PASSIVE"`.
`matches[]`	array	Cross-session face matches (see below).
`warnings[]`	array	Module-level warnings — see Liveness warnings. Each entry follows the Warning object shape (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`).

Cross-session face matches

matches[] lists the faces in your application’s history that exceeded the biometric similarity threshold against this selfie — up to 5 entries, blocklisted and allowlisted faces first, then by descending similarity. Eligible candidates are blocklisted faces, allowlisted faces, faces from Approved sessions, and faces imported against your vendor users. Faces belonging to the same user (same vendor_data, or the same vendor-user when available) are excluded from the entire search — both duplicate detection and blocklist screening. Each entry includes:

Field	Type	Description
`session_id`	string (UUID) \| null	The matched session. `null` when `source` is `imported` or `list_entry`.
`session_number`	number \| null	Sequential session number for the matched session. `null` for non-session sources.
`similarity_percentage`	number 0–100	Biometric similarity score, clamped to 0–100.
`vendor_data`	string \| null	Your reference data from the matched session (or vendor user, for imported faces).
`verification_date`	string (ISO 8601) \| null	When the matched session (or imported face) was created.
`user_details`	object \| null	`{ full_name, document_type, document_number }` from the matched session’s KYC. Imported faces populate `full_name` only (the two document fields are `null`); `null` when no details are on file.
`match_image_url`	string (signed URL) \| null	Reference face from the matched session, imported face, or list entry.
`status`	string \| null	Status of the matched session (e.g. `"Approved"`). `null` for non-session sources.
`is_blocklisted`	boolean	`true` when the matched face is on your face blocklist.
`is_allowlisted`	boolean	`true` when the matched face is on your face allowlist (duplicate-face actions are skipped).
`api_service`	string \| null	Set when the matched face came from a standalone API call (e.g. `"PASSIVE_LIVENESS"`); `null` for workflow sessions and non-session sources.
`source`	`"session" \| "imported" \| "list_entry"`	Where the matched face came from: another verification session, a face uploaded against a vendor user, or an org-managed allow/block list face.

Status values

Statuses come from the shared feature-status enum (FeatureStatusChoices).

Status	Meaning	Downstream effect
`Approved`	Face detected, liveness score above the review threshold, no auto-decline warning fired.	Counts as a successful liveness check.
`In Review`	Score at or below the review threshold but above the decline threshold, or a warning routed to review fired.	Session also moves to `In Review` until a reviewer acts.
`Declined`	An auto-decline risk fired (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, or the age risks on age-estimation flows), a configurable warning was routed to decline, or the score is at or below the decline threshold.	Session is declined unless another approved branch satisfies the workflow.
`Not Finished`	User abandoned the liveness step (or a retryable capture failure is awaiting another attempt).	The liveness branch did not produce a result.
`Resub Requested`	A reviewer requested resubmission of this step from the console.	Transient — replaced once the user re-captures.

Examples

Approved — clean active-3D capture

{
  "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 — passive liveness, low-quality capture and a possible duplicate

{
  "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"
        }
      ]
    }
  ]
}

Here the face quality (12.4) sits below the default review threshold (15), the luminance (18.7) sits below the default minimum (20), and the workflow’s duplicate-face action is set to Review — so all three warnings carry log_type: "warning" and the report resolves to In Review.

Security note

Liveness videos and selfies are biometric data — the signed URLs are temporary and expire (after 4 hours by default). Treat them as short-lived: do not cache or surface them publicly. Typically your application only needs status, score, and the warnings — store as little as possible to minimize biometric data on your servers.

Liveness warnings — full warning enum, causes, and remediation.
Webhooks — listen for session.status.updated to receive the report.
Data models — Liveness check — canonical schema with every field.
Face match report — the companion 1:1 face match against the document portrait.

Authentication

Verification

Monitoring

Platform

Overview

Where it appears in API responses

Schema

Cross-session face matches

Status values

Examples

Approved — clean active-3D capture

In Review — passive liveness, low-quality capture and a possible duplicate

Security note

​Overview

​Where it appears in API responses

​Schema

​Cross-session face matches

​Status values

​Examples

​Approved — clean active-3D capture

​In Review — passive liveness, low-quality capture and a possible duplicate

​Security note

​Related

Overview

Where it appears in API responses

Schema

Cross-session face matches

Status values

Examples

Approved — clean active-3D capture

In Review — passive liveness, low-quality capture and a possible duplicate

Security note

Related