Retrieve a Liveness Check Result

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