Skip to main content

​
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.
FieldTypeDescription
status"Approved" | "Declined" | "In Review" | "Resub Requested" | "Not Finished"Face match step status (FeatureStatusChoices).
node_idstring | nullWorkflow graph node that produced this report.
scorenumber 0–100 | nullBiometric similarity score, rounded to 2 decimals. null when no comparison was possible.
source_image_session_idstring | nullUUID 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_imagestring (signed URL)The reference image (usually the document portrait). Short-lived signed URL — download promptly, never persist the URL.
target_imagestring (signed URL)The target image (usually the liveness selfie). Short-lived signed URL — download promptly, never persist the URL.
warnings[]arrayModule-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

StatusMeaningDownstream effect
ApprovedScore above the review threshold and no auto-decline warning fired.Counts as a successful face match.
In ReviewScore above the decline threshold but at or below the review threshold.Session also moves to In Review until a reviewer acts.
DeclinedScore at or below the decline threshold, or NO_REFERENCE_IMAGE fired.Session is declined unless another approved branch satisfies the workflow.
Resub RequestedA reviewer requested resubmission of this step from the console.The user is asked to capture again.
Not FinishedThe 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.