Create a 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

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