# Retrieve a Liveness Check Result

`GET /liveness_check`

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

Retrieves the current status or final result of a previously created liveness check using the `token`
returned by the create (POST) endpoint. This endpoint is idempotent and can be safely polled until a
terminal state is reached.

## Status lifecycle

A liveness check progresses through these internal states:
- `pending`     - Created but not yet claimed by the client (no session started).
- `in_progress` - Claimed and session active / capturing.
- `complete`    - Result available (successful or failed evaluation) and this endpoint returns HTTP 200.
- `expired`     - Link validity period elapsed without completion; no result available.

While the check is `pending` or `in_progress`, this endpoint returns HTTP 202 with a descriptive message
(`Liveness check is pending` or `Liveness check is in progress`). Once processing is finished it returns HTTP 200.

If a check has expired without completion, it will return HTTP 410 with the message `Liveness check has expired`.

## Polling guidance

Recommended polling interval: 2-3 seconds. Exponential backoff is encouraged to reduce load. Stop polling
once HTTP 200 is received or if you determine from your own business logic the check should be abandoned.

## Result object

On success (HTTP 200) the response includes a `result` object mirroring what was stored for the check:
- `passed` (boolean) - Indicates whether the captured face passed the liveness evaluation.
- `confidence` (number) - Confidence score returned by the liveness provider.
- `threshold` (integer 0-99) - Either the custom value provided at creation or the system default.
- `checked_at` (datetime) - Time the result was finalized.
- `error` (string, only when failed/expired) - Terminal error code (`failed` or `expired`).

Optional fields when available:
- `image` - Base64 data URI (JPEG) of the probe frame (only if retained and not yet expired from short-term cache).
- `audit_images` - Array of objects each containing:
    * `image` - Base64 data URI (JPEG) of an intermediate frame.
    * `bounding_box` - Optional bounding box metadata (structure may evolve, treat as informational).

Images are ephemeral (cached ~30 minutes). After expiry the same result will be returned without images.

## Security considerations

Always perform this query from a trusted backend using your API key. Do not trust the client-provided
`lc_token` query parameter from the redirect alone; validate it by fetching the result here (403/400 will
protect you if the token does not belong to your account).

## Error / edge cases

- Missing or unknown `token` => HTTP 400 `Invalid check token`.
- Access without product entitlement => HTTP 403.
- Rate limiting => HTTP 429 (standard throttling rules apply).

## Parameters

| Name | In | Type | Description |
|------|----|------|-------------|
| `token` | query | string | **Required.** The token identifying the liveness check (returned from the create endpoint) Example: `u2Qe8C9vYl1kP4a7bD6fT3mN9xR5sZ0q` |

## Responses

### 200 Liveness check completed - final result returned

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Always `Ok` on success. Example: `Ok` |
| `api_reference` | string (uuid) | Unique identifier for this request (audit reference). Example: `fe4291ca-d831-4760-96df-c9cb03b3cd95` |
| `result` | object | Liveness evaluation result |
| `result.passed` | boolean | Indicates whether the subject was deemed live (true) or not (false). Example: `true` |
| `result.confidence` | number (float) | Confidence score produced by the liveness provider. Example: `87` |
| `result.threshold` | integer | Threshold applied when interpreting the score. Example: `75` |
| `result.checked_at` | string (date-time) | Timestamp when the liveness result was finalized. Example: `2026-02-17T10:15:30Z` |
| `result.error` | string | Terminal error code for failed / expired checks. Enum: `failed`, `expired` Example: `failed` |
| `result.bounding_box` | object | Optional bounding box metadata for the detected face. |
| `result.image` | string | Probe image (data URI) if still available. Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...` |
| `result.audit_images` | array of objects | Array of intermediate audit frame images if requested and available. |
| `result.audit_images[].image` | string | Audit frame image (data URI) Example: `data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...` |
| `result.audit_images[].bounding_box` | object | Optional bounding box metadata for the detected face. |

**Sample response**

```json
{
    "message": "Ok",
    "api_reference": "fe4291ca-d831-4760-96df-c9cb03b3cd95",
    "result": {
        "passed": true,
        "confidence": 87,
        "threshold": 75,
        "checked_at": "2026-02-17T10:15:30Z",
        "error": "failed",
        "bounding_box": {
            "left": 0.12,
            "top": 0.33,
            "width": 0.27,
            "height": 0.27
        },
        "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
        "audit_images": [
            {
                "image": "data:image/jpeg;base64,/9j/4AAQSkZJRgABAQ...",
                "bounding_box": {
                    "Top": 0.12,
                    "Left": 0.33,
                    "Width": 0.27,
                    "Height": 0.27
                }
            }
        ]
    }
}
```

### 202 Liveness check not yet complete (pending or in progress)

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Status message - either `Liveness check is pending` or `Liveness check is in progress`. Example: `Liveness check is in progress` |

**Sample response**

```json
{
    "message": "Liveness check is in progress"
}
```

### 410 Liveness check has expired

Content type: `application/json`

| Field | Type | Description |
|-------|------|-------------|
| `message` | string | Expiry message Example: `Liveness check has expired` |

**Sample response**

```json
{
    "message": "Liveness check has expired"
}
```

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