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

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

## Liveness Verification

The Liveness Verification module determines the genuine presence of the subject at the point at which the Selfie photograph was taken.

### Capabilities

The module returns a single capability: a liveness score.

#### Liveness score

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. A higher score indicates greater confidence that the selfie is genuine. A score of 0 indicates the check could not produce a result and should be treated as inconclusive rather than a definitive failure.

| 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"
  }
}
```

## Liveness Verification V2

### Capabilities

#### Liveness score

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. A higher score indicates greater confidence that the selfie is genuine. A score of 0 indicates the check could not produce a result and should be treated as inconclusive rather than a definitive failure.

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

#### Input payload

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

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

| Field    | Required | Description                                         |
| -------- | -------- | --------------------------------------------------- |
| `Selfie` | 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": 0
    },
    "outcome": "Fail"
  }
}
```

## Liveness Verification with Injection Attack Detection

### Capabilities

#### Face liveness result

Indicates whether the face in the selfie is determined to be live, meaning a real, physically present person was in front of the camera at the time of capture.

| Value      | Description         |
| ---------- | ------------------- |
| `Live`     | Face is live        |
| `Not Live` | Face is not live    |
| `Error`    | Face liveness error |

#### Injection attack detection result

Indicates whether an injection attack was detected during the selfie capture process. An injection attack occurs when an image is programmatically inserted into the capture pipeline rather than being captured through the device's camera in real time.

| Value      | Description                      |
| ---------- | -------------------------------- |
| `Live`     | No injection attack detected     |
| `Not Live` | Injection attack detected        |
| `Error`    | Injection attack detection error |

#### Input payload

The following is a sample payload used to submit data to the **Liveness Verification with Injection Attack Detection** module for processing.

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

| Field             | Required | Description                                         |
| ----------------- | -------- | --------------------------------------------------- |
| `EncryptedSelfie` | 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": {
      "injectionAttackDetection": "Error",
      "liveness": "Error"
    },
    "outcome": "ERROR"
  }
}
```