Endpoint

POST /v3/onboarding/{onboarding_requisition_id}/liveness/refresh

Headers

🔐

This endpoint has no request body, so no Content-Type header is required. Keep the access token on your server side and never expose it in the end user's browser.

Path Parameters

Request Examples

Reconcile the liveness verdict of a requisition:

POST /v3/onboarding/12345/liveness/refresh
X-Onboarding-Token: kR4tX0pQ7sV9nL2mB6yH8wZ3cJ1fA5dE7gT0uI9oP4s

Another requisition:

POST /v3/onboarding/67890/liveness/refresh
X-Onboarding-Token: bN8vK2rM5tQ7wE1yU3iO6pA9sD4fG0hJ2lZ5xC7vB1n

Response Details

A final verdict was found and is being applied:

{
  "worked": true,
  "enqueued": true
}

There is nothing new yet:

{
  "worked": true,
  "enqueued": false
}

Error Responses

Business Rules

What This Endpoint Is For:

• The end user finished the proof of life, but the onboarding status endpoint (GET /v3/onboarding/12345) still reports liveness_status as PENDING.
• This call asks us to re-check the verdict and pick it up, so the requisition catches up with what the end user already did.
• It is a reconciliation escape hatch for a verdict that seems stuck on PENDING — it is not part of the normal flow, which resolves on its own.

Reading the Response:

• "enqueued": true — a final verdict was found and is being applied. The result is applied asynchronously, so poll the onboarding status endpoint shortly after this call to read the new liveness_status (PASSED or FAILED) and current_step.
• "enqueued": false — there is nothing new to apply. The final verdict has not been produced yet, it has already been applied, or the re-check could not be completed this time. Keep polling the status endpoint normally, and retry this call later if the liveness is still PENDING.

No-Op Conditions:

• The call returns "enqueued": false and changes nothing when liveness_status is not PENDING — an already PASSED or FAILED liveness is never re-checked or overwritten.
• It also returns "enqueued": false when the liveness journey has not produced a final verdict yet, or when it never started.
• This endpoint never opens a new liveness journey and never consumes a liveness attempt. To start a new attempt after a FAILED liveness, use the liveness retry endpoint.

Usage Limits:

• The request carries no body. Any body sent is ignored.
• Call it sparingly and only after a reasonable wait — allow the normal flow at least a couple of minutes to resolve before reconciling.
• Do not use this endpoint as a polling loop. Poll the onboarding status endpoint to follow the journey, and call this endpoint only when the liveness stays PENDING far longer than expected.
• The call is safe to repeat: it either finds a final verdict or reports that there is none.

Access:

• Every call for a requisition must carry the X-Onboarding-Token header with the access token issued when that requisition was created.
• A missing or incorrect token returns 404 with the same message as an unknown requisition — the API does not reveal whether the requisition exists.