post
https://api.adopay.com.br/v3/onboarding/registration-update
Starts a cadastral update for the authenticated account when the registration deadline has already expired. The document and the PF/PJ type come from the account; the body carries only the contact e-mail.
Recent Requests
Log in to see full request history
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
Loading…
Endpoint
POST /v3/onboarding/registration-update
This flow is for an existing account, not for opening a new one. The document already has a registration. Call it only when Get Registration Update Status returnscan_startastrue.
Headers
| Parameter | Type | Description | Required or Optional | Example |
|---|---|---|---|---|
| Authorization | String | Bearer access token of the account holder. | required | Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIn0.example |
| Content-Type | String | Media type of the request body. Must be application/json. | required | application/json |
This endpoint does not use X-Onboarding-Token or an HMAC signature.
Body Details
{
"email": "[email protected]"
}| Field | Type | Description | Required or Optional |
|---|---|---|---|
| String | Contact e-mail used for the cadastral update. Must be a valid e-mail address; it is stored in lower case. | required |
The CPF or CNPJ and whether the update is PF or PJ are taken from the authenticated account. Do not send them in the body.
Request Examples
Start a cadastral update:
POST /v3/onboarding/registration-update
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIn0.example
Content-Type: application/json
{
"email": "[email protected]"
}Response Details
{
"worked": true,
"onboarding_requisition_id": 20401,
"onboarding_link": "https://links.example.com/onboarding/update_journey_id",
"liveness_url": null,
"liveness_status": null,
"access_token": null,
"status": "PENDING"
}When a cadastral update is already in progress for the same document, the existing requisition is returned with the same shape — no second journey is opened.
| Field | Type | Description |
|---|---|---|
| worked | Boolean | Always true for successful requests. |
| onboarding_requisition_id | Integer | Identifier of the cadastral-update requisition. |
| onboarding_link | String | Link of the hosted update pages. Send the end user to this URL. |
| liveness_url | String | Not used on this flow. Comes back null. |
| liveness_status | String | Not used on this flow. Comes back null. |
| access_token | String | Not used on this flow. Comes back null. Status of the update is read with the Bearer token. |
| status | String | Current status of the update requisition. PENDING when a new one is created. |
Error Responses
| HTTP Code | Error Message | Description |
|---|---|---|
| 400 | Atualização cadastral só é permitida quando o prazo (registration_update_deadline) estiver vencido. | The account has no expired registration deadline. Call the status endpoint and wait until can_start is true. |
| 400 | Já existe uma requisição de onboarding (criação de conta) em andamento para este documento. | The document still has an account-opening onboarding in progress. Finish or wait for that journey before starting a cadastral update. |
| 400 | Já existe uma requisição de onboarding para este documento que não é de atualização cadastral. | The document has an opening requisition that is not a cadastral update and is not in a state that allows one. |
| 400 | Company document is not a valid CPF or CNPJ. | The authenticated account document is not a valid CPF or CNPJ. |
| 400 | No onboarding layout configured for type PJ_REGISTER_UPDATE. | There is no active cadastral-update layout for this account type. Confirm with your account manager. |
| 401 | Unauthorized | Missing or invalid Bearer token. |
| 404 | Company not found | The authenticated session is not linked to an account that can start a cadastral update. |
| 422 | Validation error | The body is missing email or the value is not a valid e-mail address. |
Business Rules
When it is allowed:
- The authenticated account must have a registration deadline, and that deadline must already be in the past.
- Check
can_startonGET /v3/onboarding/registration-update/statusbefore calling this endpoint.
What is sent:
- The body carries only
email. - The document and the PF/PJ type are resolved from the authenticated account.
Re-entry:
- If a cadastral update is already open and has not reached a final decision, the existing requisition is returned instead of creating another one.
- If the previous update was rejected, a new requisition can be created.
After a successful start:
- Send the end user to
onboarding_link. - Poll
GET /v3/onboarding/registration-update/statusuntil the update is no longerIN_PROGRESS.
The account cannot start a cadastral update
Missing or invalid Bearer token
Company not found
Validation error - email is missing or invalid