Skip to main content
The Age Estimation feature emits warnings whenever a risk signal fires on the combined age + passive liveness check: the predicted age is below your minimum, the age could not be computed, the subject failed liveness, no face was found, or a presentation attack was detected. This page lists every code, what triggers it, and how to configure the workflow response.

​
Overview

Age Estimation always runs two checks in one call — a passive liveness test and an age regression model — so its warnings flow through the shared liveness pipeline and are tagged with feature LIVENESS. They appear on the report under age_estimation.warnings[] (standalone API) or liveness_checks[].warnings[] (embedded in a workflow). The warning object schema is documented under Data models — Warning object. Producers:
  • Standalone API — the endpoint generates the five warnings listed under Decline triggers.
  • Workflows — the shared liveness producers plus the age-specific checks. Age warnings only fire on age-estimation flows (adaptive age verification workflows or AGE_ESTIMATION workflow nodes) — a plain liveness step reports an estimated age but never raises age warnings.
Severities: the five auto-decline risks (NO_FACE_DETECTED, LIVENESS_FACE_ATTACK, FACE_IN_BLOCKLIST, AGE_BELOW_MINIMUM, AGE_NOT_DETECTED) are always log_type: "error" and force Declined; the remaining risks resolve to error / warning / information based on thresholds or the configured action.

​
Decline triggers

On the standalone API, the decision is Declined whenever any warning fires:
  • Age below threshold — predicted age strictly below age_estimation_decline_threshold (default 18; 0 disables the age check). Raises AGE_BELOW_MINIMUM.
  • Age not computed — no face age could be estimated (no detectable face, or no usable face for the age model). Raises AGE_NOT_DETECTED.
  • Liveness score at or below threshold — score <= face_liveness_score_decline_threshold (default 30); a null score counts as 0. Raises LOW_LIVENESS_SCORE. Suppressed when NO_FACE_DETECTED fires — the two are mutually exclusive.
  • No face detected — the liveness model found no face. Raises NO_FACE_DETECTED.
  • Presentation attack — the liveness model flagged a screen, printed photo, mask, or other spoof. Raises LIVENESS_FACE_ATTACK.
In workflows, the age checks compare the truncated estimated age (whole years) against the configured thresholds:
  • With ID-verification fallback enabled (enable_id_verification_fallback, default on): an age below borderline_minimum_age_threshold (default 18) raises AGE_BELOW_MINIMUM; ages in the borderline band (up to borderline_maximum_age_threshold) continue to document verification instead of raising a warning, and AGE_NOT_DETECTED is never raised — an undetected age routes to document verification too.
  • With fallback disabled: no estimated age raises AGE_NOT_DETECTED, and an age below minimum_age_threshold (default 18) raises AGE_BELOW_MINIMUM.

​
Configurable risks

The following risks let you tune thresholds or the action per workflow setting:
SettingRisk codeConfigurable options
Age thresholdsAGE_BELOW_MINIMUMStandalone: age_estimation_decline_threshold (default 18, 0 disables). Workflows: minimum_age_threshold / borderline_minimum_age_threshold (default 18) plus the ID-verification fallback for borderline ages.
Low Liveness ScoreLOW_LIVENESS_SCORESeparate Decline threshold (default 30 → error + decline) and Review threshold (default 60 → warning + review) applied against the liveness score.
Possible Duplicated FacePOSSIBLE_DUPLICATED_FACEAction on detection: DECLINE / REVIEW / NO_ACTION (default NO_ACTION). Workflow sessions only.
Multiple FacesMULTIPLE_FACES_DETECTEDAction on detection: DECLINE / REVIEW / NO_ACTION (default NO_ACTION). Workflow passive liveness only.
Workflow sessions also screen the face against your lists: FACE_IN_BLOCKLIST always auto-declines (error), while POSSIBLE_FACE_IN_BLOCKLIST moves the session to In Review.

​
Warnings produced

TagSeverity (log_type)Description
AGE_BELOW_MINIMUMerror — auto-declineThe estimated age is below the active threshold (standalone age_estimation_decline_threshold; workflow minimum_age_threshold / borderline_minimum_age_threshold; all default 18). additional_data is always null.
AGE_NOT_DETECTEDerror — auto-declineNo face age could be estimated. Always raised by the standalone API when the age is null; in workflows only when the ID-verification fallback is disabled.
LOW_LIVENESS_SCOREerror at/below decline threshold; warning at/below review thresholdThe liveness score is at or below the configured threshold (standalone and workflow decline default 30; workflow review default 60), indicating potential use of a static photo, screen, or video. Not raised when NO_FACE_DETECTED fires.
NO_FACE_DETECTEDerror — auto-declineNo face was detected in the submitted image. Re-prompt the user to center the camera with adequate lighting.
LIVENESS_FACE_ATTACKerror — auto-declineThe liveness model flagged a presentation attack (screen replay, printed photo, mask, deepfake).
MULTIPLE_FACES_DETECTEDPer configured action (default information, no action)More than one face was found in the image; the largest face drives the result. Workflow passive liveness only — the standalone API does not raise it.
FACE_IN_BLOCKLISTerror — auto-declineThe detected face matches an entry in your face blocklist managed via the Lists API. Workflow sessions only.
POSSIBLE_DUPLICATED_FACEPer configured action (default information, no action)The detected face is significantly similar to a previously approved face on another session (matches sharing the same vendor_data are excluded). Workflow sessions only.

​
Example

{
  "warnings": [
    {
      "risk": "LOW_LIVENESS_SCORE",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Low liveness score",
      "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data."
    },
    {
      "risk": "AGE_BELOW_MINIMUM",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Age below minimum",
      "long_description": "The age of the face is below the minimum age threshold for the application."
    }
  ]
}
In workflow decision payloads (liveness_checks[].warnings[]), each warning also carries a node_id identifying the workflow node that raised it.

​
Warning types

Each risk is assigned a severity based on your application’s configuration. Severities fall into three categories: