# Create a Liveness Check

`POST /liveness_check`

- Live: `POST https://gdapi.globaldata.net.au/api/v2/liveness_check`
- Sandbox: `POST https://sandbox-gdapi.globaldata.net.au/api/v2/liveness_check`

A liveness check evaluates whether the captured face belongs to a live human (as opposed to a spoof such as
a photo, screen, or mask).

This endpoint creates a short-lived link for performing a face liveness verification. The end user will be guided through
a liveness capture flow in their browser. Once the capture is completed (or the link expires), the result
can be retrieved using the `GET /api/v2/liveness_check?token=...` endpoint.

The resulting data will include a numeric confidence value (`confidence`), the
applied `threshold`, and a boolean `passed` indicator (see the result endpoint for details).

## Link validity

The link is valid for a configurable number of minutes (`link_valid_mins`, min 5 / max 30, default 10). After
expiry, if no result has been produced, the check will eventually be marked expired.

## Threshold

Optionally supply a custom `threshold` (0-99) that will be stored alongside the check and later echoed in the
result. If omitted, a system default (currently 70) is applied.

## Audit images

The optional `audit_images` parameter (0-4) controls how many additional intermediate frame images (beyond the
single probe image) are retained temporarily (up to ~30 minutes) for audit / review. These images (including
bounding box metadata when available) are only returned by the result endpoint when requested via `audit_images` > 0
during creation.

## Webhooks

If a `webhook_url` is supplied, lifecycle events (e.g. completion / expiry) may be posted to that URL. Webhook
invocations are not retried indefinitely; implement idempotency on your side.

### Webhook Signature Verification

When a `webhook_url` is provided and an event (e.g. completion / expiry) occurs, a POST request is sent with a
JSON body and a `Signature` HTTP header.

The `Signature` header is an HMAC SHA-256 hex digest of the payload generated using the `secret` returned at creation time.

### IP Whitelisting for Webhooks

Webhooks will originate from one of the IP addresses listed in:

[IP whitelisting for webhooks](/docs/guides/globaldata_api/ip-whitelisting-for-webhooks)

## Return URL Redirect & lc_token

After the user completes the liveness flow (or the flow reaches a terminal state), the browser will be redirected
to your supplied `return_url` with an added query parameter:

`?lc_token={token}`

Example:
`https://example.com/return?lc_token=u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q`

IMPORTANT: Do not trust the `lc_token` value from the client redirect. Always treat it as untrusted input and
fetch the definitive result from the API using `GET /api/v2/liveness_check?token=...` under your authenticated
server context. This ensures the token belongs to your account and has not been tampered with.

On terminal failure states, an additional `error` parameter may be appended:

`?lc_token={token}&error=failed`
or
`?lc_token={token}&error=expired`

If your `return_url` already contains query parameters, these values will be appended using `&` instead of `?`.

## Request body

Parameters to create the liveness check link

| Field | Type | Description |
|-------|------|-------------|
| `return_url` | string (url) | **Required.** URL to redirect / link back to after the user completes the liveness flow. Example: `https://example.com/return` |
| `webhook_url` | string (url) | Optional webhook URL to receive event callbacks (e.g. completion / expiry). Example: `https://example.com/webhook` |
| `link_valid_mins` | integer [5..30] | Number of minutes the liveness link remains valid (default 10, min 5, max 30). Default: `10` Example: `10` |
| `threshold` | integer [0..99] | Custom threshold (0-99) applied when interpreting the liveness score. Defaults to system configured value. Example: `70` |
| `audit_images` | integer [0..4] | Number of additional audit frame images (0-4) to retain for short-term retrieval in the result response. Example: `2` |

**Sample request**

```json
{
    "return_url": "https://example.com/return",
    "webhook_url": "https://example.com/webhook",
    "link_valid_mins": 10,
    "threshold": 70,
    "audit_images": 2
}
```

## Responses

### 200 Liveness check created successfully

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | A message indicating the result (`Ok` on success). Example: `Ok` |
| `api_reference` | string (uuid) | Unique identifier for this request (for support / audit tracing). Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `token` | string | Token used to reference the liveness check (supply to the result endpoint). Example: `u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q` |
| `url` | string (url) | The user-facing liveness capture URL (sandbox or live domain depending on environment). Example: `https://sandbox-idcheck.globaldata.net.au/liveness/u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q` |
| `secret` | string | Secret associated with this check (may be required for some subsequent secured operations). Example: `7f6a1e88-b6d2-4d8a-9f3f-5c4d2b1a0e9f` |
| `webhook_url` | string (url) | Echoed only when a non-null webhook_url was supplied. Example: `https://example.com/webhook` |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "token": "u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q",
    "url": "https://sandbox-idcheck.globaldata.net.au/liveness/u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q",
    "secret": "7f6a1e88-b6d2-4d8a-9f3f-5c4d2b1a0e9f",
    "webhook_url": "https://example.com/webhook"
}
```

Standard error responses: 400, 401, 402, 403, 429, 5XX (see [Common error responses](/docs/reference/general/common-error-responses.md))