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

# Liveness Verification

The **Liveness Verification** module determines whether a real, physically present person was in front of the camera at the point the selfie photograph was taken. It detects presentation attacks such as:

* Attempts to spoof the verification process using a printed photograph
* A screen replay
* A video recording
* A 3D mask

The module returns a confidence score indicating the likelihood that the captured selfie represents a genuine, live person.

This page contains documentation for the **Liveness Verification** module, including its capabilities and the scoring thresholds it uses.

## Liveness Verification

The **Liveness Verification** module analyses a selfie image captured during the onboarding journey and produces a score that reflects the system's confidence in the subject's genuine presence.

It's typically placed alongside or before the **Facematch Verification** module, which compares the selfie against the photograph on the subject's identity document. Liveness verification confirms the person is real and present; facematch verification confirms they are the same person shown on the document.

Liveness verification is also supported as a standalone module. It can run on its own in a journey without requiring a Facematch Verification or document module to precede it. This is useful for use cases where confirming genuine human presence is the only check needed.

### Capabilities

The module returns a single capability: a liveness score.

#### Liveness score

This capability returns an integer score from 0 to 100 indicating the system's confidence that the selfie was captured from a real, physically present person at the time of the photograph.

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

A higher score indicates greater confidence that the selfie is genuine. A lower score indicates a higher likelihood that the image is a presentation attack or does not represent a live person.

The score reflects the combined output of multiple analysis signals, which may include

* **Texture analysis**: Detecting the flat, reflective surface of a printed photo or screen.
* **Depth estimation**: Distinguishing a three-dimensional face from a two-dimensional image.
* **Edge and boundary detection**: Identifying the borders of a held-up photograph or device screen.

A score of `0` indicates that the liveness check could not produce a result. This may occur if the selfie image was corrupted, if no face was detected in the image, or if a system error prevented analysis. Evaluation rules should treat a score of `0` as an inconclusive result rather than a definitive failure.

#### Default outcomes

The module uses score thresholds to classify the liveness result into one of three outcomes. These thresholds are pre-configured as default outcomes and can be used in evaluation and routing logic within the journey designer.

| Outcome   | Condition                       | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| --------- | ------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Success` | Score ≥ 75                      | The system has high confidence that a real, live person was present when the selfie was captured. The journey can proceed to downstream biometric checks such as facematch verification.                                                                                                                                                                                                                                                                                |
| `Review`  | Score ≥ 60 and \< 75            | The system's confidence is moderate. The selfie may be genuine, but the analysis detected some signals that could indicate a presentation attack, or the image quality reduced the system's ability to make a definitive determination. Common causes include poor lighting, extreme camera angles, or partial face occlusion. This outcome typically routes to manual review, where a human operator can visually inspect the selfie and the surrounding session data. |
| `Fail`    | Score \< 60                     | The system has low confidence in genuine presence. The selfie is likely a presentation attack, a photograph of a photograph, a screen replay, a mask, or a digitally injected image. This outcome typically routes to rejection or escalation, depending on your fraud policy.                                                                                                                                                                                          |
| `ERROR`   | Default (no conditions matched) | The liveness check could not be completed. This fallback outcome typically indicates a system-level issue, such as a service outage or image processing failure, rather than a spoofing attempt. For updates on status, check the [GBG system status page](https://www.gbgstatus.com/).                                                                                                                                                                                 |

### Input payload

The following is a sample payload used to submit a selfie image to the **Liveness Verification** module for processing.

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

| Field        | Required | Description                                             |
| ------------ | -------- | ------------------------------------------------------- |
| `faceImage`  | Yes      | Base64-encoded selfie image captured from the end user. |
| `biometrics` | Yes      | Accepts at least one item.                              |

### Sample response

The following is a sample response for a successful liveness check from the **Liveness Verification** module.

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