Create Onboarding Requisition

Endpoint

POST /v3/onboarding/form

Your application renders the registration form. The only page the end user opens on our side is liveness_url — and an onboarding configured without the proof of life opens no page at all: liveness_url and liveness_status come back null and the journey starts at the form, which then carries a SELFIE per partner.

Headers

Parameter	Type	Description	Required or Optional	Example
Content-Type	String	Media type of the request body. Must be `application/json`.	required	application/json

🔑 This endpoint takes no authentication header. It returns an access_token that identifies the requisition. Every later call requires that value in the X-Onboarding-Token header.

Body Details

{
  "document_legal_id": "11222333000181",
  "email": "contact@example.com",
  "onboarding_type": "PJ",
  "representative_document": "111.444.777-35",
  "whitelabel_sigla": "EXAMPLE"
}

Field	Type	Description	Required or Optional
document_legal_id	String	CPF (individual) or CNPJ (company) being onboarded. A masked value is accepted — dots, slashes and dashes are removed before processing — and the check digits are validated. Send it as a JSON string. A number is rejected with `400` (`Input should be a valid string`): JSON drops a leading zero, so a document starting with `0` would arrive truncated.	required
email	String	Contact email of the person or company being onboarded. Must be a valid email address; it is stored in lower case.	required
onboarding_type	String	Type of onboarding: `PF` for an individual (the document must be a valid CPF) or `PJ` for a company (the document must be a valid CNPJ).	required
representative_document	String	CPF of the legal representative, who is also the person who performs the liveness when it is required. Required for `PJ`. A masked value is accepted and the check digits are validated. Send it as a JSON string. A number is rejected with `400` (`Input should be a valid string`): JSON drops a leading zero, so a document starting with `0` would arrive truncated. Do not send it for `PF`.	required for PJ / omit for PF
whitelabel_sigla	String	Code of the white-label brand that runs the journey, up to 50 characters. The code must match an existing brand. When it is not sent, the default brand is used.	optional

Request Examples

Individual (PF):

POST /v3/onboarding/form
Content-Type: application/json

{
  "document_legal_id": "123.456.789-09",
  "email": "maria.santos@example.com",
  "onboarding_type": "PF"
}

Company (PJ) with a white-label brand:

POST /v3/onboarding/form
Content-Type: application/json

{
  "document_legal_id": "11222333000181",
  "email": "financeiro@example.com",
  "onboarding_type": "PJ",
  "representative_document": "111.444.777-35",
  "whitelabel_sigla": "EXAMPLE"
}

Response Details

Success Status Codes

HTTP Code	When it is returned
201	A new onboarding requisition was created. The body carries the `access_token`.
200	The document already has an onboarding in progress. The existing requisition is returned and the body carries no `access_token` — reuse the one you stored when the requisition was created.

201 Created:

{
  "worked": true,
  "onboarding_requisition_id": 12345,
  "onboarding_link": null,
  "liveness_url": "https://links.example.com/liveness/example_journey_id",
  "liveness_status": "PENDING",
  "access_token": "kJ3xQ9example_access_token_value",
  "status": "PENDING"
}

Document with an onboarding already in progress (200 OK):

{
  "worked": true,
  "onboarding_requisition_id": 12345,
  "onboarding_link": null,
  "liveness_url": "https://links.example.com/liveness/example_journey_id",
  "liveness_status": "PENDING",
  "access_token": null,
  "status": "IN_PROGRESS"
}

Field	Type	Description
worked	Boolean	Always `true` for successful requests.
onboarding_requisition_id	Integer	Unique identifier of the onboarding requisition. Use it in the path of every other endpoint of this journey.
onboarding_link	String	Always `null`. The only link the end user may open is `liveness_url`, and only when the proof of life is required.
liveness_url	String	Link where the end user completes the proof of life. Only returned while `liveness_status` is `PENDING`, and `null` when the onboarding is configured without the proof of life.
liveness_status	String	Status of the proof of life. `PENDING` right after creation, or `null` when the onboarding is configured without it. Possible values: `PENDING`, `PASSED`, `FAILED`, `null`.
access_token	String	Opaque token of this requisition, returned only when the requisition is created. Send it in the `X-Onboarding-Token` header of every other endpoint. `null` when an existing requisition is returned with 200.
status	String	Current status of the requisition. `PENDING` on a newly created requisition. Possible values: `PENDING`, `IN_PROGRESS`, `APPROVED`, `REPROVED`, `COMPLETED`.

Requisition status (status):

Value	Description
`PENDING`	The requisition was created and the journey has not been analysed yet
`IN_PROGRESS`	The journey is being processed
`APPROVED`	The journey was approved
`REPROVED`	The journey was rejected
`COMPLETED`	The journey is finished

Liveness status (liveness_status):

Value	Description
`PENDING`	The proof of life was opened and is waiting for the end user
`PASSED`	The end user completed the proof of life successfully
`FAILED`	The proof of life was not successful; a new attempt may be started
`null`	The onboarding is configured without the proof of life

Error Responses

HTTP Code	Error Message	Description
400	Seu cadastro está em análise interna.	The document already has a registration that was approved by the journey and is waiting for the internal review. A new requisition cannot be created while the review is open.
400	Cadastro aprovado. Sua conta está ativa.	The document already has an approved registration and an active account, so a new onboarding is not needed.
400	Não foi possível prosseguir com seu cadastro.	The document is in a state that does not allow a new onboarding requisition.
400	Documento já possui cadastro. Para atualização cadastral, use o fluxo de registration-update.	The document already went through a registration update. Use the registration update flow instead of creating a new onboarding requisition.
400	Whitelabel não encontrada para a sigla informada.	The `whitelabel_sigla` sent does not match any existing white-label brand. Check the code with your account manager.
400	No onboarding layout configured for type PJ_FORM.	There is no active own-form layout for the `onboarding_type` sent. Confirm the type with your account manager.
422	Validation error	Request validation failed: invalid CPF or CNPJ (format, length or check digits), invalid email address, missing required field, a `document_legal_id` that does not match the `onboarding_type`, or — on `PJ` — a missing, empty or invalid `representative_document`.

Business Rules

Request Path:

Use POST /v3/onboarding/form to start the journey.

Document Validation:

document_legal_id must have between 11 and 14 characters after the mask is removed.
onboarding_type PF requires a valid CPF; onboarding_type PJ requires a valid CNPJ.
Check digits are validated. An invalid CPF or CNPJ is rejected with 422.
Masked documents are accepted (123.456.789-09, 11.222.333/0001-81) and normalised before processing.

Legal representative (PJ):

representative_document is required when onboarding_type is PJ. A missing, empty or invalid CPF is rejected with 422 (Invalid representative CPF).
Do not send the field for PF.
Masked values are accepted (111.444.777-35) and stored as digits only.
The partner is created at this step, with that CPF and is_legal_representative as true. When the proof of life is required, that is the person who must complete it — the CAF no longer reads an identity document to identify who is on camera.
When you later submit the form, the partner marked as legal representative must be this same CPF.

One Requisition per Document:

A document that already has an onboarding in progress does not create a second requisition: the existing one is returned with HTTP 200.
The 200 response does not repeat the access_token. Store the token from the 201 response — it is the only time it is returned.
A document whose previous onboarding was rejected can start a new requisition: a new 201 is returned, with a new access_token.
A document whose registration is already approved, or is waiting for the internal review, is refused with 400 and a message explaining the situation.
A document that already went through a registration update is refused with 400 and must use the registration update flow.

Access Token:

The access_token is returned once, when the requisition is created.
Store it together with the onboarding_requisition_id: it is required in the X-Onboarding-Token header of every other endpoint (status, form submission, liveness retry and liveness refresh).
A missing or wrong token answers 404 Onboarding requisition not found. on those endpoints — the requisition is never disclosed to a caller that cannot present its token.

Journey:

When the proof of life is required, the response carries liveness_url and liveness_status: "PENDING". Send the end user to liveness_url and poll GET /v3/onboarding/{onboarding_requisition_id} until liveness_status becomes PASSED before submitting the form.
When the onboarding runs without the proof of life, both fields come back null and the form can be submitted right away, with a SELFIE per partner.
onboarding_link always comes back null.
liveness_url is only available while the proof of life is pending. Once it is completed or fails, the link is no longer returned.
For a company (PJ) onboarding, the official registry data is looked up in the background right after creation and becomes available in the status endpoint, together with representative_document.

White-Label Brand:

whitelabel_sigla selects the brand that appears in the journey.
The code must match an existing brand, otherwise the request is refused with 400.
When the field is not sent, the default brand is used.