Liveness warnings

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.
Duplicate face identity mismatch	`DUPLICATED_FACE_NAME_MISMATCH`	Own setting (`face_liveness_duplicated_face_name_mismatch_action`): No action / Review (default) / Decline. Only evaluated when `DUPLICATED_FACE` also fires — see below.
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.

Capture channel integrity

Injection-attack signals reported by the client at capture time. Unlike presentation attacks (an artefact held in front of a real camera), these describe the camera feed itself being replaced or intercepted. Each is configurable per workflow and defaults to no action, so enabling the feature changes no decisions until you opt in.

Risk	Cause	Config key	Default
`VIRTUAL_CAMERA_DETECTED`	The capture device was identified as a software virtual camera (OBS, ManyCam, Snap Camera, DroidCam and similar) rather than a physical camera.	`virtual_camera_action`	`NO_ACTION`
`EXTERNAL_CAPTURE_DEVICE_DETECTED`	The capture device was an external camera or a capture card rather than a built-in camera.	`external_capture_device_action`	`NO_ACTION`
`FRAME_INJECTION_SUSPECTED`	The captured frames show indicators of software compositing or injection into the camera pipeline rather than a genuine live capture, or the capture was performed on emulated or virtualized hardware (an Android emulator, or a desktop virtual machine), where no physical camera sensor exists and every frame is supplied by the host.	`frame_injection_action`	`NO_ACTION`
`SCREEN_CAPTURE_DURING_CAPTURE`	Screen recording or screen sharing was active on the device during the biometric capture.	`screen_capture_action`	`NO_ACTION`

Browsers expose no OS-level camera-source attestation to any vendor, so on web these signals are corroborating evidence rather than proof. On web, a verdict of null means not determined (device labels are unavailable until camera permission is granted) and never fires a risk.

A virtual camera is identified by its device name, so a camera the operating system presents under an ordinary name is not recognised that way. Inside an Android emulator the remapped camera is labelled like any built-in one, which is why the emulated-hardware case is reported through FRAME_INJECTION_SUSPECTED instead: it is detected from the device environment - the rendering stack and the device model reported in the user agent - rather than the camera name. Findings raised from the device environment carry additional_data.reason: "emulated_capture_device", distinguishing them from the liveness model’s own frame analysis.

Detecting the machine from a browser is evidence, not attestation, and a determined attacker can interfere with it. The native mobile SDKs report stronger, operating-system-level integrity signals a browser cannot see (emulator, rooted or jailbroken device, runtime hooking, attached debugger), each with its own configurable action under Device and runtime integrity. These signals raise the attacker’s cost considerably, but on their own they do not prove that a capture came from a genuine device. Device integrity signals are independent of the liveness method, so they combine with any of Passive, 3D Flash or 3D Action & Flash.

Recording sanity forensics

LIVENESS_VIDEO_ANOMALY is computed server-side on the stored liveness recording, independently of the liveness model. It detects a moving sequence repeated across multiple cycles, consistent with a looped feed.

Risk	Cause	Config key	Default
`LIVENESS_VIDEO_ANOMALY`	The recording contains a repeated moving sequence. Camera stalls, repeated still frames, dark lead-ins and slow frame delivery alone do not raise this signal.	`face_liveness_video_anomaly_action`	`NO_ACTION`

Set the action on your Liveness or Age Estimation node: NO_ACTION records an information finding, REVIEW can escalate a decided verification to In Review, and DECLINE can escalate it to Declined. The check runs asynchronously, so an escalation can arrive after the initial result. A more severe existing decision is not downgraded, and manual review decisions are preserved. Version 2 findings include forensics_version: 2, repeated_sequence evidence and repeated_moving_sequence in anomaly_reasons. Delivery measurements such as unique_frame_ratio, static_pair_ratio, decoded_fps_ratio and max_frame_gap_seconds remain diagnostics; they cannot establish a replay on their own. Older findings describe the detector version used at the time and are not retroactively reclassified.

This is a conservative additional signal, not complete detection of synthetic media or injected video. A recording with no anomaly is not proof of liveness. Short or ambiguous captures and captures without usable replay evidence remain unflagged by this check. Missing or unreadable recordings produce no finding from this check; other verification checks still apply.

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
`DUPLICATED_FACE_NAME_MISMATCH`	Emitted alongside `DUPLICATED_FACE` when the matched session’s identity does not match this session’s resolved name (ID document, `expected_details`, or linked vendor user), using the same name-match scoring and threshold as ID verification. A face reused under a different name is a stronger fraud signal than a plain duplicate, so it carries its own configurable action.	`duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score`	Configurable — `warning` by default. Never relaxes `DUPLICATED_FACE`’s own configured outcome, only escalates it.

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 mutually exclusive codes appears per report. DUPLICATED_FACE_NAME_MISMATCH is not part of that precedence group: it is an additional code emitted on top of DUPLICATED_FACE when the identity check also fails, never in its place. additional_data.name_match_score never carries the names being compared — only ids and a score, so no PII lands in the warning payload.

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.
`LIVENESS_VIDEO_ANOMALY`	Liveness video stream anomaly	The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.
`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.
`DUPLICATED_FACE_NAME_MISMATCH`	Duplicated face under a different name	The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.
`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.

Duplicate face under a different name

"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": "information",
    "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"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.",
    "node_id": "liveness_primary"
  }
]

DUPLICATED_FACE stays at its own configured action (here, No action — log_type: "information") while DUPLICATED_FACE_NAME_MISMATCH carries its own action, defaulting to Review (log_type: "warning"). The liveness report’s status follows the most severe of the two: In Review here, even though the plain duplicate-face setting alone would not have flagged it.

Recording sanity anomaly with its measurements

"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]

This example shows the replay evidence from a recording containing three copies of a moving sequence. log_type is information because the configured action is NO_ACTION. The frame-delivery diagnostics, omitted from this example for brevity, do not trigger the finding.

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[].

Authentication

Verification

Monitoring

Platform

Overview

Auto-decline conditions

Configurable verification settings

Warnings produced

Core liveness

Capture channel integrity

Recording sanity forensics

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

Duplicate face under a different name

Recording sanity anomaly with its measurements

Warning types

​Overview

​Auto-decline conditions

​Configurable verification settings

​Warnings produced

​Core liveness

​Capture channel integrity

​Recording sanity forensics

​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

​Duplicate face under a different name

​Recording sanity anomaly with its measurements

​Warning types

​Related

Overview

Auto-decline conditions

Configurable verification settings

Warnings produced

Core liveness

Capture channel integrity

Recording sanity forensics

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

Duplicate face under a different name

Recording sanity anomaly with its measurements

Warning types

Related