Age Estimation Warnings

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:

Setting	Risk code	Configurable options
Age thresholds	`AGE_BELOW_MINIMUM`	Standalone: `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 Score	`LOW_LIVENESS_SCORE`	Separate Decline threshold (default `30` → `error` + decline) and Review threshold (default `60` → `warning` + review) applied against the liveness score.
Possible Duplicated Face	`POSSIBLE_DUPLICATED_FACE`	Action on detection: `DECLINE` / `REVIEW` / `NO_ACTION` (default `NO_ACTION`). Workflow sessions only.
Multiple Faces	`MULTIPLE_FACES_DETECTED`	Action 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

Tag	Severity (`log_type`)	Description
`AGE_BELOW_MINIMUM`	`error` — auto-decline	The 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_DETECTED`	`error` — auto-decline	No 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_SCORE`	`error` at/below decline threshold; `warning` at/below review threshold	The 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_DETECTED`	`error` — auto-decline	No face was detected in the submitted image. Re-prompt the user to center the camera with adequate lighting.
`LIVENESS_FACE_ATTACK`	`error` — auto-decline	The liveness model flagged a presentation attack (screen replay, printed photo, mask, deepfake).
`MULTIPLE_FACES_DETECTED`	Per 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_BLOCKLIST`	`error` — auto-decline	The detected face matches an entry in your face blocklist managed via the Lists API. Workflow sessions only.
`POSSIBLE_DUPLICATED_FACE`	Per 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:

Age Estimation overview — feature behavior, pricing, and decision logic.
Age Estimation report — full response shape for both the standalone API and the embedded workflow value.
Standalone API reference — POST /v3/age-estimation/ request and response.
Passive liveness — the shared liveness model used in age-estimation responses.
Data models — age estimation — canonical field-by-field schema.

Authentication

Verification

Monitoring

Platform

Overview

Decline triggers

Configurable risks

Warnings produced

Example

Warning types

​Overview

​Decline triggers

​Configurable risks

​Warnings produced

​Example

​Warning types

​Related

Overview

Decline triggers

Configurable risks

Warnings produced

Example

Warning types

Related