Liveness warnings - Didit Documentation

Overview

Warnings on the liveness report flag every condition Didit observed while running the liveness check. They land in the warnings[] array on each item of liveness_checks[] (see Liveness report), with feature set to "LIVENESS". Each entry follows the shared warning object shape: feature, risk, additional_data, log_type, short_description, long_description, node_id. Every warning has three layers:

The risk code — a stable identifier you can match on in your code (the codes listed below).
The log_type — one of information, warning, or error. Auto-decline risks always carry error. For configurable risks it is derived from the configured action: No action → information, Review → warning, Decline → error. For threshold-driven risks (LOW_LIVENESS_SCORE, LOW_FACE_QUALITY) it is error when the value crosses the decline threshold and warning when it only crosses the review threshold.
The decision impact — the same routing drives the liveness report’s status: a Review action moves it to In Review, a Decline action (or any auto-decline risk) to Declined, and No action leaves it untouched.

Some risks are emitted only when the liveness method is PASSIVE (multiple-faces, quality, and luminance checks). The tables below list the full set of liveness risk codes and their severities — no other liveness risk codes exist.

Auto-decline conditions

The following risks always force the liveness report (and the session) to Declined, with log_type: "error":

Risk	Trigger
`NO_FACE_DETECTED`	No face was located during the liveness capture, or the user exhausted retry attempts.
`LIVENESS_FACE_ATTACK`	The model detected a presentation attack (mask, screen replay, deepfake-class spoof).
`FACE_IN_BLOCKLIST`	The face matched an entry on your application’s face blocklist.
`AGE_BELOW_MINIMUM`	Estimated age below the configured minimum. Only emitted on adaptive age-verification workflows and `AGE_ESTIMATION` nodes.
`AGE_NOT_DETECTED`	Age could not be estimated. Only emitted on age-estimation flows with ID-verification fallback disabled.

When NO_FACE_DETECTED fires, LOW_LIVENESS_SCORE is suppressed (there is no face to score).

Configurable verification settings

In the Didit console, liveness risks are grouped under the following workflow settings:

Group	Risks	Configuration
Liveness score thresholds	`LOW_LIVENESS_SCORE`	Review threshold + decline threshold on `score`. At or below review → `In Review`; at or below decline → `Declined`.
Duplicate face action	`DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE`	One shared setting: No action (default) / Review / Decline. Skipped entirely when the matching face is in your face allowlist.
Possible blocklisted face	`POSSIBLE_FACE_IN_BLOCKLIST`	Not configurable in workflows — always routed to Review (`log_type: "warning"`).
Multiple faces action (passive only)	`MULTIPLE_FACES_DETECTED`	No action (default) / Review / Decline.
Face quality thresholds (passive only)	`LOW_FACE_QUALITY`	Review threshold (default 15) + decline threshold (default 0, i.e. decline disabled).
Face luminance (passive only)	`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`	Min / max thresholds (defaults 20 / 80 on the normalized 0–100 scale) + a per-direction action (default Review).
Age thresholds (adaptive workflows / `AGE_ESTIMATION` node)	`AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED`	Minimum and borderline age thresholds; both risks auto-decline the liveness step. With ID-verification fallback enabled, the workflow routes the user to a document check instead of ending the session.

Warnings produced

Core liveness

Risk	Cause	Severity	Affects status?	Remediation
`NO_FACE_DETECTED`	No face located during the capture, or the user exhausted retry attempts (`MAX_ATTEMPTS_REACHED`).	`error`	Auto-decline	Re-capture in better lighting; ensure the face is centered.
`LIVENESS_FACE_ATTACK`	Model detected a presentation attack.	`error`	Auto-decline	Treat as fraud. The session is automatically declined.
`LOW_LIVENESS_SCORE`	`score` at or below the workflow’s review threshold. Suppressed when `NO_FACE_DETECTED` is also present.	`warning`; escalates to `error` when the score is at or below the decline threshold	Configurable (review / decline thresholds)	Re-capture; tune thresholds if you observe false positives.

Cross-session face matching

Risk	Cause	Additional data	Severity
`FACE_IN_BLOCKLIST`	Face matched a blocklisted face.	`blocklisted_session_id`, `blocklisted_session_number`, `api_service`	`error` — auto-decline
`POSSIBLE_FACE_IN_BLOCKLIST`	Face matched a blocklisted face at a lower-confidence band.	`blocklisted_session_id`, `blocklisted_session_number`, `api_service`	`warning` — always routed to Review in workflows
`FACE_IN_ALLOWLIST`	Face matched an allowlisted face.	`allowlisted_session_id`, `allowlisted_session_number`, `api_service`	`information` — duplicate-face action skipped
`POSSIBLE_FACE_IN_ALLOWLIST`	Face matched an allowlisted face at a lower-confidence band.	`allowlisted_session_id`, `allowlisted_session_number`, `api_service`	`information` — possible duplicate-face action skipped
`DUPLICATED_FACE`	Face matched an already-approved face from another user (an `Approved` session with different `vendor_data`, or a face imported against one of your vendor users).	`duplicated_session_id`, `duplicated_session_number`, `api_service`	Configurable — `information` by default
`POSSIBLE_DUPLICATED_FACE`	Face matched another approved or imported face at a lower-confidence band.	`duplicated_session_id`, `duplicated_session_number`, `api_service`	Configurable — `information` by default

For matches against imported faces or list-entry faces (which have no session), the *_session_id, *_session_number, and api_service values in additional_data are null. Faces belonging to the same user (same vendor_data, or the same vendor user when available) are excluded from the entire index search — both duplicate detection and blocklist screening. Match precedence is: blocklist exact → allowlist exact → duplicate exact → blocklist possible → allowlist possible → duplicate possible — only one of these six codes appears per report.

Passive liveness quality (only when `method = "PASSIVE"`)

Risk	Cause	Severity	Remediation
`MULTIPLE_FACES_DETECTED`	More than one face was visible during the capture. The largest face is always used for scoring and matching.	Configurable — `information` by default	Recapture solo.
`LOW_FACE_QUALITY`	Face quality below the review threshold (default 15).	`warning`; `error` when below the decline threshold (default 0 — decline disabled)	Better focus / less occlusion / centered face.
`LOW_FACE_LUMINANCE`	Normalized luminance below the minimum threshold (default 20).	Configurable — `warning` by default (action defaults to Review)	Better lighting.
`HIGH_FACE_LUMINANCE`	Normalized luminance above the maximum threshold (default 80).	Configurable — `warning` by default (action defaults to Review)	Reduce lighting; avoid backlight.

LOW_FACE_LUMINANCE and HIGH_FACE_LUMINANCE are mutually exclusive — the luminance is either below the minimum or above the maximum, never both.

Age estimation (adaptive workflows and `AGE_ESTIMATION` nodes)

Risk	Cause	Severity	Remediation
`AGE_BELOW_MINIMUM`	Estimated age below the configured minimum (or borderline threshold when ID-verification fallback is enabled).	`error`	Workflow falls back to ID verification when configured.
`AGE_NOT_DETECTED`	Age could not be estimated and ID-verification fallback is disabled.	`error`	Enable fallback or re-capture.

Exact description strings

The API returns these exact short_description and long_description strings for each risk:

`risk`	`short_description`	`long_description`
`NO_FACE_DETECTED`	No Face Detected in liveness	The system couldn’t identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.
`LIVENESS_FACE_ATTACK`	Liveness Face Attack	The system detected a potential attempt to bypass the liveness check.
`LOW_LIVENESS_SCORE`	Low liveness score	The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.
`FACE_IN_BLOCKLIST`	Face in blocklist	The system identified a face in the blocklist, which means the face is not allowed to be verified.
`POSSIBLE_FACE_IN_BLOCKLIST`	Possible face in blocklist	The system identified a possible face in the blocklist, which means the face is not allowed to be verified.
`FACE_IN_ALLOWLIST`	Face in allowlist	The face matched the application’s face allowlist, so duplicate-face actions were skipped for this signal.
`POSSIBLE_FACE_IN_ALLOWLIST`	Possible face in allowlist	The face possibly matched the application’s face allowlist, so possible duplicate-face actions were skipped for this signal.
`DUPLICATED_FACE`	Duplicated face from other approved session	The system identified a duplicated face from another approved session, requiring further investigation.
`POSSIBLE_DUPLICATED_FACE`	Possible duplicated face from other approved session	The system identified a possible duplicate face from another approved session, requiring further investigation.
`MULTIPLE_FACES_DETECTED`	Multiple faces detected	Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.
`LOW_FACE_QUALITY`	Low face quality	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.
`LOW_FACE_LUMINANCE`	Low face luminance	The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.
`HIGH_FACE_LUMINANCE`	High face luminance	The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.
`AGE_BELOW_MINIMUM`	Age below minimum	The age of the face is below the minimum age threshold for the application.
`AGE_NOT_DETECTED`	Age not detected	The system couldn’t identify the age of the face, which is necessary for document verification.

Standalone passive liveness API

The standalone Liveness API reuses the same risk codes with a few behavioral differences:

NO_FACE_DETECTED and LOW_LIVENESS_SCORE are mutually exclusive — the score check only runs when a face was found. LOW_LIVENESS_SCORE fires against the request’s face_liveness_score_decline_threshold (default 30) and always carries log_type: "error".
POSSIBLE_FACE_IN_BLOCKLIST is treated as a decline (log_type: "error") instead of review.
MULTIPLE_FACES_DETECTED carries log_type: "warning", while the duplicate-face risks stay informational. Only error-level warnings flip the standalone response’s status to Declined.
Standalone warning entries include feature but no node_id.

Examples

Auto-decline on detected attack

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_FACE_ATTACK",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Liveness Face Attack",
    "long_description": "The system detected a potential attempt to bypass the liveness check.",
    "node_id": "liveness_primary"
  }
]

Configurable warnings on a passive capture

"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": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Multiple faces detected",
    "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.",
    "node_id": "liveness_primary"
  }
]

Duplicate face with payload

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]

Here the duplicate-face action is set to Review, so the warning carries log_type: "warning" and the liveness report’s status is In Review. With the default (No action) it would carry log_type: "information" instead. api_service is null because the matched face came from a workflow session, not a standalone API call.

Warning types

Each risk is assigned a severity based on your application’s configuration. The three severities are:

Liveness report — full report schema and statuses.
Face match warnings — companion 1:1 face match warnings.
Webhooks — session.status.updated carries the warnings as soon as the liveness step finishes.
Data models — Liveness check — canonical schema with every field.
Data models — Warning object — the shape of every entry in warnings[].

​Overview

​Auto-decline conditions

​Configurable verification settings

​Warnings produced

​Core liveness

​Cross-session face matching

​Passive liveness quality (only when method = "PASSIVE")

​Age estimation (adaptive workflows and AGE_ESTIMATION nodes)

​Exact description strings

​Standalone passive liveness API

​Examples

​Auto-decline on detected attack

​Configurable warnings on a passive capture

​Duplicate face with payload

​Warning types

​Related