Face search warnings

Overview

Face Search emits a small set of warnings so your team can tell why a search returned Approved or Declined. Warnings are returned in the face_search.warnings[] array of the POST /v3/face-search/ response (see Face Search report). Warnings here use a reduced shape compared with workflow warnings: there is no node_id. The documented response contract declares five fields — risk, additional_data, log_type, short_description, long_description — and the runtime payload additionally carries feature, which is always "LIVENESS" on this endpoint.

Warnings produced

Risk	Cause	Severity (`log_type`)	Affects status	Recommended remediation
`FACE_IN_BLOCKLIST`	The search image matched a face in your application’s face blocklist above the high-confidence similarity band.	`error`	Forces `Declined`.	Reject the user. Investigate the linked session via `additional_data.blocklisted_session_id`.
`POSSIBLE_FACE_IN_BLOCKLIST`	A blocklisted face matched within the lower “possible” similarity band, below the high-confidence band.	`error`	Forces `Declined` on the standalone Face Search API (stricter than the workflow liveness check, which sends this risk to review).	Manual review. Confirm the hit against the original blocklist evidence before acting.
`MULTIPLE_FACES_DETECTED`	More than one face was found in the submitted search image. The search still runs, using the largest detected face.	`warning`	None — never declines on its own.	Re-capture with a single subject in frame if the largest face is not the intended one.
`DUPLICATED_FACE`	The face matched, above the high-confidence band, a face from an approved session or an imported user-profile face. The standalone endpoint does not exclude same-`vendor_data` sessions, so a returning user matches their own earlier sessions.	`information`	None — duplicates are surfaced as signal, not declines.	Investigate the linked session via `additional_data.duplicated_session_id`. Decide whether to block or merge accounts on your side.
`POSSIBLE_DUPLICATED_FACE`	Same as `DUPLICATED_FACE` but the similarity sits in the lower “possible” band rather than the high-confidence band.	`information`	None.	Manual review before treating the two records as the same person.

Producer: FaceSearchAPIView.add_warnings (apis/views/face_search.py:250-330); status derivation: get_face_search_status (apis/views/face_search.py:242-248), which declines only for the two blocklist risks. Emission rules worth knowing:

Blocklist takes precedence over duplicates. A confirmed blocklist hit suppresses DUPLICATED_FACE, and a possible blocklist hit suppresses POSSIBLE_DUPLICATED_FACE — you never get both members of a pair for the same confidence band.
additional_data references the first matching face only, even when matches[] contains several. Blocklist warnings carry {blocklisted_session_id, blocklisted_session_number, api_service}; duplicate warnings carry {duplicated_session_id, duplicated_session_number, api_service}; MULTIPLE_FACES_DETECTED carries null. The api_service value is uppercase (e.g. PASSIVE_LIVENESS) or null for workflow sessions.
Allowlisted faces suppress duplicate warnings — a high-confidence allowlist match clears DUPLICATED_FACE/POSSIBLE_DUPLICATED_FACE (it never clears blocklist warnings).

Exact warning strings

Risk	`short_description`	`long_description`
`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.
`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.

Search-image gate

When no face is detected in user_image, the API rejects the request with HTTP 400 and {"error": "No face detected in the image"} before a face_search object is built — so a NO_FACE_DETECTED warning never appears in a successful Face Search response. This is returned as a top-level error string, not in warnings[].

Configurable settings

The similarity bands that split confirmed hits (FACE_IN_BLOCKLIST, DUPLICATED_FACE) from possible hits (POSSIBLE_FACE_IN_BLOCKLIST, POSSIBLE_DUPLICATED_FACE) are fixed internally — per-application threshold tuning applies to the workflow liveness check, not this endpoint. The switches you control per request are:

search_type (most_similar, default | blocklisted_or_approved) — most_similar ranks every enrolled face by similarity; blocklisted_or_approved restricts candidates to blocklisted faces, allowlisted faces, faces from approved sessions, and imported user-profile faces, ranking blocklisted entries first.
save_api_request (default true) — persists the call as an API-type session and enrolls the searched face into your face search index. Faces enrolled by Face Search calls are excluded from future Face Search results. Set to false to query without storing or enrolling.
rotate_image (default false) — tries 90-degree rotations and keeps the orientation with the best face detection; useful when EXIF orientation is missing.

Examples

Blocklist hit (forces `Declined`)

{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}

Duplicate signal (status stays `Approved`)

{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "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."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "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."
    }
  ]
}

Face Search report — full response shape
Face Search API reference — request parameters
Face Match warnings — 1:1 selfie-to-document warnings (separate from Face Search)
Data models — Face Search — canonical schema

Authentication

Verification

Monitoring

Platform

Overview

Warnings produced

Exact warning strings

Search-image gate

Configurable settings

Examples

Blocklist hit (forces `Declined`)

Duplicate signal (status stays `Approved`)

Warning types

​Overview

​Warnings produced

​Exact warning strings

​Search-image gate

​Configurable settings

​Examples

​Blocklist hit (forces Declined)

​Duplicate signal (status stays Approved)

​Related

​Warning types

Overview

Warnings produced

Exact warning strings

Search-image gate

Configurable settings

Examples

Blocklist hit (forces `Declined`)

Duplicate signal (status stays `Approved`)

Related

Warning types