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

# Facematch Verification

export const VersionWarningBanner = () => {
  const [latestUrl, setLatestUrl] = useState(null);
  useEffect(() => {
    if (typeof window === "undefined") return;
    const {pathname, hash, search} = window.location;
    if (!pathname.includes("/go-v1/")) return;
    setLatestUrl(`${pathname.replace("/go-v1/", "/go-v2/")}${search}${hash}`);
  }, []);
  if (!latestUrl) return null;
  return <div className="not-prose my-6 rounded-xl border border-amber-500/30 bg-amber-500/10 px-4 py-3 text-sm text-gray-800 dark:text-gray-100">
      ⚠️ You are viewing the <strong>GBG GO v1</strong> documentation.
      <a href={latestUrl} className="ml-2 font-medium underline text-amber-700 dark:text-amber-400 hover:text-amber-800 dark:hover:text-amber-300">
        View the latest version (v2) →
      </a>
    </div>;
};

<VersionWarningBanner />

The **Facematch Verification** module determines whether two face images belong to the same person. It compares a selfie captured during the onboarding journey against a reference face image. The reference is typically the portrait extracted from the subject's identity document or read from the document's Near Field Communication (NFC) chip. Liveness verification confirms that a real person is present. Facematch verification confirms that the person present is the same person shown on the document.

## Facematch Verification

The FaceMatch Verification module will determine the similarity between two provided face images

### Capabilities

The module returns a single capability: a facematch score.

#### Facematch score

Returns an integer similarity score indicating how closely the selfie matches the reference face image. A higher score indicates greater similarity. A score of 0 indicates the comparison could not produce a result and should be treated as inconclusive rather than a confirmed mismatch.

| Detail  | Description |
| ------- | ----------- |
| Type    | Integer     |
| Range   | 0–100       |
| Default | `0`         |

A higher score indicates greater similarity between the two faces. The score reflects the algorithm's confidence that the selfie and the document portrait belong to the same person, based on analysis of facial geometry, feature positioning, and biometric markers.

Factors that can reduce the score without indicating fraud include:

* Significant time elapsed between the document photo and the selfie (ageing).
* Changes in appearance such as facial hair, glasses, hairstyle, poor lighting.
* Camera quality during selfie capture, low resolution or damage to the document photograph.
* Differences in head angle or facial expression between the two images.

A score of `0` indicates that the comparison couldn't produce a result. This occurs if no face was detected in the selfie, if the anchor image was missing or unreadable, or if an error prevented the comparison. Evaluation rules should treat a score of `0` as an inconclusive result rather than a confirmed mismatch.

## Default outcomes

The module uses score thresholds to classify the facematch result into one of three outcomes.

| Outcome   | Condition                       | Description                                                                                                                                                                                                                                                                                                                                                                                     |
| --------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Success` | Score ≥ 80                      | The system has high confidence that the selfie and the document portrait belong to the same person. The subject is confirmed as the document holder.                                                                                                                                                                                                                                            |
| `Review`  | Score ≥ 70 and \< 80            | The system's confidence is moderate. The faces might belong to the same person, but the similarity score is not high enough for automatic acceptance. Common causes include poor lighting, a significant age gap between the document photo and the selfie, or partial face occlusion. This outcome typically routes to manual review, where a human operator visually compares the two images. |
| `Fail`    | Score \< 70                     | The system has low confidence that the faces belong to the same person. The selfie and the document portrait are likely of different individuals. This outcome typically routes to rejection or escalation.                                                                                                                                                                                     |
| `ERROR`   | Default (no conditions matched) | The facematch check could not be completed due to a system-level issue.                                                                                                                                                                                                                                                                                                                         |

<Note>
  The default score thresholds (80 for success, 70 for review) are starting points. Adjust them in the evaluation configuration to match your risk tolerance. Lowering the success threshold increases acceptance rates but allows weaker matches through. Raising it improves security but might route more genuine users to manual review, particularly for documents with older photographs.
</Note>

## Input payload

The following is a sample payload used to submit biometric images to the **Facematch Verification** module for processing.

```json JSON theme={null}
{
  "resourceId": "<resourceId>",
  "context": {
    "subject": {
      "biometrics": [
        {
          "face1Image": "<base64-encoded string>",
          "face2Image": "<base64-encoded string>"
        }
      ]
    }
  }
}
```

The following table describes each field in the payload.

| Field        | Required | Description                                                                                                                                            |
| ------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `face1Image` | Yes      | Base64-encoded selfie image captured from the end user.                                                                                                |
| `face2Image` | Yes      | Base64-encoded anchor image used for comparison. Sourced from a document processed earlier in the journey or from an existing trusted reference image. |
| `biometrics` | Yes      | Accepts at least one item.                                                                                                                             |

## Sample response

The following is a sample response for a successful facematch from the **Facematch Verification** module.

```json JSON theme={null}
{
  "response": {
    "advice": {
      "score": 82
    },
    "outcome": "Success"
  }
}
```

## Facematch Verification - NIST

### Capabilities

#### Facematch result

Indicates whether the face in the selfie matches the face in the reference image.

| Value      | Description         |
| ---------- | ------------------- |
| `Match`    | Face is matched     |
| `No Match` | Face is not matched |

## Input payload

The following is a sample payload used to submit data to the **Facematch Verification - NIST** module for processing.

```json JSON theme={null}
{
  "context": {
    "subject": {
      "biometrics": [
        {
          "anchorImage": "<base64-image>",
          "selfieImage": "<base64-image>"
        }
      ],
      "identity": {}
    }
  }
}
```

| Field         | Required | Description                                         |
| ------------- | -------- | --------------------------------------------------- |
| `Selfie`      | Yes      | \[Describe.] {/* TODO: written by the docs team */} |
| `AnchorImage` | Yes      | \[Describe.] {/* TODO: written by the docs team */} |

## Sample response

The following is a sample response returned by the module.

```json JSON theme={null}
{
  "response": {
    "advice": {
      "facematchResult": "No Match"
    },
    "outcome": "Fail"
  }
}
```

## Facematch Verification V2

### Capabilities

#### Facematch score

Returns an integer similarity score indicating how closely the selfie matches the reference face image. A higher score indicates greater similarity. A score of 0 indicates the comparison could not produce a result and should be treated as inconclusive rather than a confirmed mismatch.

| Detail  | Description |
| ------- | ----------- |
| Type    | Integer     |
| Range   | 0–100       |
| Default | `0`         |

## Input payload

The following is a sample payload used to submit data to the **Facematch Verification V2** module for processing.

```json JSON theme={null}
{
  "context": {
    "subject": {
      "biometrics": [
        {
          "face1Image": "<base64-image>",
          "face2Image": "<base64-image>"
        }
      ],
      "identity": {}
    }
  }
}
```

| Field         | Required | Description                                         |
| ------------- | -------- | --------------------------------------------------- |
| `Selfie`      | Yes      | \[Describe.] {/* TODO: written by the docs team */} |
| `AnchorImage` | Yes      | \[Describe.] {/* TODO: written by the docs team */} |

## Sample response

The following is a sample response returned by the module.

```json JSON theme={null}
{
  "response": {
    "advice": {
      "score": 65
    },
    "outcome": "Fail"
  }
}
```