> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.
# Liveness report
> Read Didit's Liveness report: status, confidence score, detection method, age estimation, cross-session face matches, and where it appears in responses.
## 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](/sessions-api/retrieve-session).
* **Webhooks** — `session.status.updated` payloads include the same `liveness_checks[]` array once the step has produced data. See [Webhooks](/integration/webhooks).
* **Standalone liveness API** — see [Liveness standalone API](/standalone-apis/passive-liveness).
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/data-models#liveness-check) 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](/core-technology/liveness/warnings-liveness). Each entry follows the [Warning object](/reference/data-models#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
```json theme={null}
{
"liveness_checks": [
{
"status": "Approved",
"node_id": "liveness_primary",
"method": "ACTIVE_3D",
"score": 92.4,
"reference_image": "https:///.../reference.jpg?signature=...",
"video_url": "https:///.../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
```json theme={null}
{
"liveness_checks": [
{
"status": "In Review",
"node_id": "liveness_primary",
"method": "PASSIVE",
"score": 76.1,
"reference_image": "https:///.../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:///.../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.
## Related
* [Liveness warnings](/core-technology/liveness/warnings-liveness) — full warning enum, causes, and remediation.
* [Webhooks](/integration/webhooks) — listen for `session.status.updated` to receive the report.
* [Data models — Liveness check](/reference/data-models#liveness-check) — canonical schema with every field.
* [Face match report](/core-technology/face-match/report-face-match) — the companion 1:1 face match against the document portrait.