Endpoint

POST /v3/onboarding/form

📘

Your application renders the registration form. The only page the end user opens on our side is liveness_url.

Headers

🔑

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": "[email protected]",
  "onboarding_type": "PJ",
  "representative_document": "111.444.777-35",
  "whitelabel_sigla": "EXAMPLE"
}

Request Examples

Individual (PF):

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

{
  "document_legal_id": "123.456.789-09",
  "email": "[email protected]",
  "onboarding_type": "PF"
}

Company (PJ) with a white-label brand:

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

{
  "document_legal_id": "11222333000181",
  "email": "[email protected]",
  "onboarding_type": "PJ",
  "representative_document": "111.444.777-35",
  "whitelabel_sigla": "EXAMPLE"
}

Response Details

Success Status Codes

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"
}

Requisition status (status):

Liveness status (liveness_status):

Error Responses

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. That is the person who must complete the liveness — 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:

• The response carries liveness_url and liveness_status: "PENDING". onboarding_link comes back null.
• Send the end user to liveness_url and poll GET /v3/onboarding/{onboarding_requisition_id} until liveness_status becomes PASSED before submitting the form.
• 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.