Skip to main content

​
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.
FieldTypeDescription
status"Approved" | "Declined" | "In Review" | "Not Finished" | "Resub Requested"Liveness-step status (see below).
node_idstring | nullWorkflow graph node that produced this report.
method"ACTIVE_3D" | "FLASHING" | "PASSIVE"The liveness method that produced this capture.
scorenumber 0–100 | nullLiveness confidence score, rounded to 2 decimals.
reference_imagestring (signed URL) | nullReference selfie extracted from the capture. Signed URL with a limited validity window.
video_urlstring (signed URL) | nullFull liveness capture video (active methods). Signed URL with a limited validity window.
age_estimationnumber | nullEstimated age in years of the largest face in the reference image.
face_qualitynumber 0–100 | nullPassive-liveness face quality, normalized to a percentage. Populated only when method = "PASSIVE".
face_luminancenumber 0–100 | nullPassive-liveness facial luminance, normalized from 0–255 to a percentage. Populated only when method = "PASSIVE".
matches[]arrayCross-session face matches (see below).
warnings[]arrayModule-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:
FieldTypeDescription
session_idstring (UUID) | nullThe matched session. null when source is imported or list_entry.
session_numbernumber | nullSequential session number for the matched session. null for non-session sources.
similarity_percentagenumber 0–100Biometric similarity score, clamped to 0–100.
vendor_datastring | nullYour reference data from the matched session (or vendor user, for imported faces).
verification_datestring (ISO 8601) | nullWhen the matched session (or imported face) was created.
user_detailsobject | 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_urlstring (signed URL) | nullReference face from the matched session, imported face, or list entry.
statusstring | nullStatus of the matched session (e.g. "Approved"). null for non-session sources.
is_blocklistedbooleantrue when the matched face is on your face blocklist.
is_allowlistedbooleantrue when the matched face is on your face allowlist (duplicate-face actions are skipped).
api_servicestring | nullSet 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).
StatusMeaningDownstream effect
ApprovedFace detected, liveness score above the review threshold, no auto-decline warning fired.Counts as a successful liveness check.
In ReviewScore 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.
DeclinedAn 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 FinishedUser abandoned the liveness step (or a retryable capture failure is awaiting another attempt).The liveness branch did not produce a result.
Resub RequestedA 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.