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

> Compare a selfie against a document portrait in GBG GO to confirm the person present is the same individual shown on the identity document.

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

The module has two variants. Both compare a selfie against a document portrait, but they differ in result type and the level of control over matching thresholds.

| Variant                              | Result type               | Threshold control | Review tier   |
| ------------------------------------ | ------------------------- | ----------------- | ------------- |
| [NIST](#facematch-verification-nist) | Binary (Match / No Match) | None              | Not available |
| [V2](#facematch-verification-v2)     | Numeric score (0–100)     | Configurable      | Available     |

<AccordionGroup>
  <Accordion title="Facematch Verification - NIST">
    The NIST variant compares the selfie image against the anchor image (the portrait extracted from the identity document) and returns a binary match or no-match result. It uses a face recognition algorithm independently evaluated under the NIST Face Recognition Vendor Test (FRVT) programme.

    ## Capabilities

    The module returns a single capability: the facematch result.

    ### Facematch result

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

    | Code       | Label    | Description                                                                                                                                                                                                                                                                        |
    | ---------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `Match`    | Match    | The two face images are determined to belong to the same person. The selfie captured during the journey matches the portrait photograph on the subject's identity document.                                                                                                        |
    | `No Match` | No Match | The two face images are determined to belong to different people. The selfie doesn't match the document portrait. This may indicate that the person presenting the document isn't the document holder or a low-quality document photograph is captured. This is the default value. |

    ## Default outcomes

    | Outcome   | Condition                       | Description                                                                                                                                                                            |
    | --------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | `Success` | Facematch result is `Match`     | The selfie matches the document portrait. The subject is confirmed as the document holder.                                                                                             |
    | `Fail`    | Facematch result is `No Match`  | The selfie doesn't match the document portrait. Depending on your use case, this may route to manual review, a request to recapture the selfie, or rejection.                          |
    | `ERROR`   | Default (no conditions matched) | The facematch check couldn't be completed due to a system-level issue. This may occur if the selfie or anchor image couldn't be processed, or if no face was detected in either image. |

    ## 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      | A selfie image of the subject, used for biometric comparison.           |
    | `AnchorImage` | Yes      | A trusted reference image of the subject to compare the selfie against. |

    ## Sample response

    The following is a sample response for a successful facematch from the **Facematch Verification - NIST** variant.

    ```json JSON theme={null}
    {
      "response": {
        "advice": {
          "contains": {
            "facematchResult": "Match"
          }
        },
        "outcome": "Success"
      }
    }
    ```
  </Accordion>

  <Accordion title="Facematch Verification V2">
    The V2 variant compares the selfie image against the anchor image and produces a similarity score from 0 to 100, where a higher score indicates greater similarity between the two faces. This gives you more control over how strictly you enforce the match, since you can configure the acceptance threshold to suit your risk tolerance.

    ## 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 may 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. You can adjust these thresholds in the evaluation configuration to match their risk tolerance. Lowering the success threshold increases acceptance rates but allows weaker matches through. Raising it improves security but may increase the number of genuine users routed to manual review, particularly for documents with older photographs.
    </Note>

    ## 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      | A selfie image of the subject, used for biometric comparison.           |
    | `AnchorImage` | Yes      | A trusted reference image of the subject to compare the selfie against. |

    ## Sample response

    The following is a sample response returned by the module.

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

  <Accordion title="Choosing between variants">
    The two variants serve the same purpose but differ in how they report results and how much control they give the you over the matching decision.

    |                         | NIST                                                                                | v2                                                                                                    |
    | ----------------------- | ----------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
    | **Result type**         | Binary (Match / No Match)                                                           | Numeric score (0–100)                                                                                 |
    | **Threshold control**   | None: the algorithm applies its own internal threshold                              | Configurable: You set the success and review thresholds                                               |
    | **Review tier**         | Not available: result is either match or no match                                   | Available: scores between the review and success thresholds route to manual review                    |
    | **Algorithm assurance** | Independently evaluated under NIST FRVT                                             | Not specified                                                                                         |
    | **Best suited for**     | If you want a definitive yes/no determination with independently validated accuracy | If you want granular control over acceptance thresholds and a manual review tier for borderline cases |
  </Accordion>

  <Accordion title="Facematch verification">
    ## 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** module for processing.

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

    ## Sample response

    The following is a sample response returned by the module.

    ```json JSON theme={null}
    {
      "response": {
        "advice": {
          "score": 82
        },
        "outcome": "Fail"
      }
    }
    ```
  </Accordion>
</AccordionGroup>