> ## Documentation Index
> Fetch the complete documentation index at: https://docs.didit.me/llms.txt
> Use this file to discover all available pages before exploring further.

# Face match report

> How to read Didit's face match 1:1 report: status, similarity score, source/target image URLs, warnings, and where the data appears in API responses.

## 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](/standalone-apis/face-match) 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](/sessions-api/retrieve-session).
* **Webhooks** — `session.status.updated` payloads include the same `face_matches[]` array once the step has produced data. See [Webhooks](/integration/webhooks).
* **Standalone Face Match API** — for direct 1:1 comparisons, see [Face Match standalone API](/standalone-apis/face-match).

<Note>
  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.
</Note>

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#face-match) 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](/core-technology/face-match/warnings-face-match).                      |

## 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

```json theme={null}
{
  "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

```json theme={null}
{
  "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

```json theme={null}
{
  "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.

## Related

* [Face match warnings](/core-technology/face-match/warnings-face-match) — full warning enum, causes, and remediation.
* [Liveness report](/core-technology/liveness/report-liveness) — the upstream step that captures the target image.
* [Webhooks](/integration/webhooks) — listen for `session.status.updated` to receive the report.
* [Data models — Face match](/reference/data-models#face-match) — canonical schema with every field.