Face match report

Overview

The face match report captures a 1:1 biometric comparison between the live selfie captured during liveness and a reference image — most commonly the portrait extracted from the ID document. It returns a single 0–100 similarity score, signed URLs for the two compared images, the source session for the reference image, and any warnings raised by the match. The report is produced after the user completes both the liveness step and the document step in a workflow (or, for portrait-based workflows such as biometric authentication, after liveness alone), or directly via the standalone Face Match API when you supply two arbitrary face images yourself. Each report carries its own status — independent of the overall session status — that reflects how the face match step alone resolved:

Approved — score is above the review threshold and no auto-decline warning fired.
In Review — score is between the decline and review thresholds.
Declined — score is at or below the decline threshold, or NO_REFERENCE_IMAGE fired.
Resub Requested — a reviewer requested the user resubmit this step from the console.
Not Finished — the face match step has not produced a result yet (including while the user is retrying a failed capture).

Where it appears in API responses

The face match report ships inside the face_matches[] array — always a JSON array, never a singular face_match object. It is null until at least one face-match step has produced data, and multiple entries appear when a workflow runs face match more than once.

Session decision API — GET /v3/session/{sessionId}/decision/ returns face_matches[] at the top level. See Retrieve session decision.
Webhooks — session.status.updated payloads include the same face_matches[] array once the step has produced data. See Webhooks.
Standalone Face Match API — for direct 1:1 comparisons, see Face Match standalone API.

Read response.face_matches[0] and iterate the array — the singular face_match shape some older tutorials referenced does not exist on the v3 decision endpoint.

Schema

The canonical field-by-field schema lives on the Data models reference page. The fields below mirror that canonical schema.

Field	Type	Description
`status`	`"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"`	Face match step status (`FeatureStatusChoices`).
`node_id`	string \| null	Workflow graph node that produced this report.
`score`	number 0–100 \| null	Biometric similarity score, rounded to 2 decimals. `null` when no comparison was possible.
`source_image_session_id`	string \| null	UUID of the session whose stored portrait supplied the reference (source) image — set in portrait-based flows (biometric authentication, or a portrait supplied at session creation). `null` when the reference image is the document portrait captured in the same session.
`source_image`	string (signed URL)	The reference image (usually the document portrait). Short-lived signed URL — download promptly, never persist the URL.
`target_image`	string (signed URL)	The target image (usually the liveness selfie). Short-lived signed URL — download promptly, never persist the URL.
`warnings[]`	array	Module-level warnings. Each entry carries `feature` (always `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, and `node_id` — see Face match warnings.

Status values

Status	Meaning	Downstream effect
`Approved`	Score above the review threshold and no auto-decline warning fired.	Counts as a successful face match.
`In Review`	Score above the decline threshold but at or below the review threshold.	Session also moves to `In Review` until a reviewer acts.
`Declined`	Score at or below the decline threshold, or `NO_REFERENCE_IMAGE` fired.	Session is declined unless another approved branch satisfies the workflow.
`Resub Requested`	A reviewer requested resubmission of this step from the console.	The user is asked to capture again.
`Not Finished`	The face match step has not produced a result (an input was missing, the workflow never reached the compare step, or the user is still inside the capture-retry loop).	The branch did not complete.

Low-similarity failures are retried before the status sticks: the user gets up to face_match_max_attempts captures (3 by default), and only the final attempt’s score is applied. Custom status rules configured on the workflow node can further adjust the resulting status, combining with the score-derived status under Declined > In Review > Approved precedence.

Examples

Approved — clean match

{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}

In Review — borderline similarity

{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

Declined — no reference image to compare against

{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}

Security note

The signed URLs for source_image and target_image are biometric data and expire after a short validity window. Treat them as short-lived: do not cache or surface them publicly. Typically your application only needs status and score — store as little as possible to minimize biometric data on your servers.

Face match warnings — full warning enum, causes, and remediation.
Liveness report — the upstream step that captures the target image.
Webhooks — listen for session.status.updated to receive the report.
Data models — Face match — canonical schema with every field.

Authentication

Verification

Monitoring

Platform

Overview

Where it appears in API responses

Schema

Status values

Examples

Approved — clean match

In Review — borderline similarity

Declined — no reference image to compare against

Security note

​Overview

​Where it appears in API responses

​Schema

​Status values

​Examples

​Approved — clean match

​In Review — borderline similarity

​Declined — no reference image to compare against

​Security note

​Related

Overview

Where it appears in API responses

Schema

Status values

Examples

Approved — clean match

In Review — borderline similarity

Declined — no reference image to compare against

Security note

Related