Get Onboarding Requisition Status

Endpoint

GET /v3/onboarding/{onboarding_requisition_id}

Headers

Path Parameters

Request Examples

Poll while the end user completes the proof of life:

GET /v3/onboarding/10482
X-Onboarding-Token: kR4tX0pQ7sV9nL2mB6yH8wZ3cJ1fA5dE7gT0uI9oP4s

Poll after the form was submitted:

GET /v3/onboarding/10483
X-Onboarding-Token: 7wD2sN9kV4bX1mQ6tL3yH8pZ0cR5fJ2aE7gU4iO1nS6

Response Details

Waiting for the liveness (individual onboarding):

{
  "worked": true,
  "onboarding_requisition_id": 10482,
  "onboarding_type": "PF",
  "status": "PENDING",
  "status_internal": null,
  "liveness_status": "PENDING",
  "current_step": "LIVENESS",
  "liveness_url": "https://liveness.example.com/start/abc123def456",
  "liveness_attempts_left": 2,
  "submitted_at": null,
  "company": null,
  "representative_document": null,
  "updated_at": "2026-09-04T14:19:04Z"
}

After the form was submitted (company onboarding):

{
  "worked": true,
  "onboarding_requisition_id": 10483,
  "onboarding_type": "PJ",
  "status": "IN_PROGRESS",
  "status_internal": null,
  "liveness_status": "PASSED",
  "current_step": "PROCESSING",
  "liveness_url": null,
  "liveness_attempts_left": 2,
  "submitted_at": "2026-09-04T12:00:00Z",
  "company": {
    "official_name": "Example Company LTDA",
    "fantasy_name": "Example Company",
    "opening_date": "2015-03-12",
    "legal_nature": "Limited Liability Company",
    "legal_nature_code": "2062",
    "main_activity": "Custom computer programming services",
    "main_activity_code": "6201-5/01",
    "joint_stock": "100000.00",
    "zip_code": "90010150",
    "state": "RS",
    "city": "Porto Alegre",
    "street": "Avenida Borges de Medeiros",
    "neighborhood": "Centro Historico",
    "number": "1000",
    "complement": "Suite 302"
  },
  "representative_document": "11144477735",
  "updated_at": "2026-09-04T15:02:47Z"
}

Response Fields

Company Fields

Present only when onboarding_type is PJ. Every field is returned individually and may come back null while the official registry lookup has not returned yet, so your form must keep collecting the editable data regardless.

Onboarding Type Values

Verification Status Values

Analysis Status Values

null means nobody has decided yet.

Liveness Status Values

null means the onboarding is configured without the proof of life: there is no journey to wait for, and the form must carry a SELFIE per partner.

Status Dimensions

The response carries three independent status fields plus one consolidated step:

Journey Steps

current_step is the value your application should branch on while the journey runs:

Error Responses

Business Rules

Access:

• Every call must send the X-Onboarding-Token header with the access_token returned when the onboarding requisition was created.
• A token is valid for a single onboarding requisition.
• A missing or incorrect token returns 404 with the same message used for an unknown identifier: the API never confirms whether a requisition exists to a caller that does not hold its token.
• Store the access token when the requisition is created; it is not returned again by this endpoint.

Liveness:

• liveness_url is returned only while liveness_status is PENDING. Once the proof of life passes or fails, the field comes back null and the previous link must not be reused.
• liveness_attempts_left starts at 2: a requisition allows at most 3 proof-of-life journeys in total and the first one is already opened when the requisition is created. The field decreases by 1 every time a further journey is opened, and reaches 0 on the last available attempt.
• A new attempt can only be opened after a FAILED proof of life and only while liveness_attempts_left is greater than 0.
• If liveness_status stays on PENDING after the end user has finished the proof of life, call POST /v3/onboarding/{onboarding_requisition_id}/liveness/refresh to reconcile the result, then read this endpoint again.

Company Data:

• The company object is returned only for PJ onboardings. For PF onboardings it is always null.
• The registry lookup runs asynchronously: the object can be returned with all fields null right after creation and filled in a later poll.
• Do not block your form on this data. Collect the editable fields from the end user and send them in the form submission.

Legal representative:

• representative_document is the CPF sent as representative_document on POST /v3/onboarding/form. It is returned only for PJ onboardings.
• Use it to pre-fill the legal-representative partner on your form. The submit call must mark that same CPF as is_legal_representative — a different one is rejected with 400 — and, when the proof of life is required, it is also the person who passed it.

Important Notes:

• All dates and times are returned in UTC-0, in ISO 8601 with the Z suffix (for example, 2026-09-04T14:19:04Z).
• status_internal is null until a decision is made; treat null as "still in progress", never as a rejection.
• submitted_at is null until the form is submitted and never changes afterwards.
• This endpoint is read-only and can be called at any point of the journey, including after current_step reaches DONE.

Polling Recommendations:

• Poll every 3 to 5 seconds while the end user is on the proof of life, so your screen reacts as soon as current_step moves from LIVENESS to FORM.
• Poll every 10 to 30 seconds while current_step is PROCESSING or REVIEW.
• Stop polling once current_step reaches DONE.
• Use updated_at to detect whether anything changed between two polls.