Retry Liveness Verification

Time	Status	User Agent
Retrieving recent requests…

Endpoint

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

Parameter	Type	Description	Required or Optional	Example
X-Onboarding-Token	String	The access token returned when the onboarding requisition was created. It authorizes every request made for that specific requisition.	required	6Qq1tVv0dYb8Hs3NfXk2Lm9ZrPj7CwEu4AaGtRb1SxM

This endpoint has no request body, so no Content-Type header is required.

Parameter	Type	Description	Required	Example
onboarding_requisition_id	Integer	Identifier of the onboarding requisition returned when it was created.	Yes	12345

Start another liveness attempt:

POST /v3/onboarding/12345/liveness/retry
X-Onboarding-Token: 6Qq1tVv0dYb8Hs3NfXk2Lm9ZrPj7CwEu4AaGtRb1SxM

{
  "worked": true,
  "liveness_url": "https://liveness.example.com/journey/9f2c7a41example",
  "liveness_attempts_left": 1
}

Field	Type	Description
worked	Boolean	Always `true` for successful requests.
liveness_url	String	Link to the new liveness journey. Send the end user to this link so the proof of life can be performed again.
liveness_attempts_left	Integer	How many liveness attempts are still available after the one just opened. `0` means no further retry will be accepted.

HTTP Code	Error Message	Description
400	Liveness is not in a state that allows another attempt.	The current liveness is not `FAILED`. A new attempt can only be started after a failed one. Check `liveness_status` before calling this endpoint.
400	All liveness attempts have been used.	No liveness attempt is left for this requisition. The registration cannot proceed and no new attempt is opened. Match on the `400` status code, not on the message text.
400	Liveness retry is only available on the own-form flow.	The requisition was not created for the own-form journey, which is the only journey where liveness attempts are managed by your application.
404	Onboarding requisition not found.	The requisition does not exist, or the `X-Onboarding-Token` header is missing or does not match the token issued for this requisition.

When a retry is allowed:

The requisition must have been created with POST /v3/onboarding/form.
For a company (PJ) the same legal representative whose CPF was sent as representative_document at creation must perform the new attempt.
liveness_status must be FAILED. Calling this endpoint while the liveness is PENDING (still in progress) or PASSED (already approved) is rejected with 400.
At least one liveness attempt must still be available.
The X-Onboarding-Token issued when the requisition was created must be sent on every call.

Attempt limit:

Each onboarding requisition allows a maximum of 3 liveness attempts by default, counting the first one opened at creation.
liveness_attempts_left in the response reports how many attempts remain after the attempt this call just opened. When it returns 0, the end user is on the last available attempt and a further retry will be refused.
The same counter is available at any time in the liveness_attempts_left field of the onboarding status endpoint.
Once the attempts run out, the call fails with 400 and the registration cannot proceed. Stop the journey in your interface and direct the end user to your support channel; calling the creation endpoint again for the same document returns the same requisition, it does not open a new one.

What changes after a successful call:

A new liveness journey is opened and its link is returned in liveness_url. Discard the previous link: only the new one is tracked by the requisition, and a result produced on the old link is no longer applied.
The requisition goes back to a pending liveness: liveness_status returns to PENDING and current_step stays on LIVENESS.
The attempt counter is incremented immediately, even if the end user never opens the new link.

Important Notes:

Send the end user to the new liveness_url and keep polling the onboarding status endpoint until liveness_status becomes PASSED, exactly as you did for the first attempt.
While liveness_status is PENDING, the onboarding status endpoint also returns the current liveness_url, so the link can be recovered without calling this endpoint again.
Do not call this endpoint to recover a verdict that seems stuck on PENDING. That is not a failed attempt: the call is rejected with 400 and no attempt is consumed. Use the liveness refresh endpoint instead.
The form can only be submitted after the liveness has passed, so no data collected in your form is lost while a new attempt is in progress.