Account Onboarding

The Accreditation APIs let you open accounts for your end customers — individuals (PF) and companies (PJ) — programmatically, with identity verification through facial biometrics.

How it works

The process has four major stages:

1. Identity verification (facial biometrics) — every individual involved (the holder for PF; every partner for PJ) must have their identity verified through facial biometrics.
2. Company documents (PJ only) — upload the PDFs required by company.legalForm via POST /v1/accreditations/{id}/documents (in parallel with biometrics). Details in PJ account opening.
3. Review — depending on the flow, the opening is approved automatically or goes through prior review by an analyst.
4. Account opening at the settlement partner — after approval, the account is opened and automatically bound to your tenant. You receive the final accountId and can start operating (PIX, boletos, statement, etc.).

There are two biometrics flows:

State machine

Every accreditation goes through the following state machine:

Statuses

Tracking progress

You have two complementary ways to track each accreditation:

• Webhooks (recommended) — the accreditation.updated event is emitted on every state transition, plus specific events (facial link created, account active, failure). See Onboarding Webhooks.
• Polling — GET /v1/accreditations/pf and GET /v1/accreditations/pj return the aggregated status and per-person details (biometrics state, link, expiration).

The optional callbackUri field brings the holder back to your app when they finish their step, with the outcome in the URI — useful for the experience, but it does not replace either of the two ways above. See Returning to your app.

Tenant binding

The CPF/CNPJ is only bound to the tenant after biometry is confirmed. While PENDING_BIOMETRY, there is no accountId and POST does not deduplicate: repeating with the same document creates another accreditation (201). Cancel abandoned pendings with POST /v1/accreditations/{id}/cancel (FAILED / errorReason=cancelled).

After confirmation, the settlement account is automatically bound to the tenant that created the accreditation — no extra activation step. A further POST for a document already claimed by your own tenant returns 409 already_accredited.

Accounts shared between tenants

A PF account can be operated by more than one tenant, when the holder authorizes each of them through the consent flow (Holder who already has an account). In that case:

• It is the same account — balance, statement and Pix keys are shared. Each tenant has its own accountId pointing to it.
• Every authorized tenant receives the webhooks for each movement. Operations originated outside your API (by another authorized tenant or by the holder) arrive with external: true.
• Previous authorizations are not revoked when a new tenant is authorized. If you already operated the account and receive account.shared_access.granted, another tenant started operating it too — if that does not make sense for your case, talk to support.
• The holder can revoke any of these accesses through support; from then on the revoked tenant’s calls for that account return 403.

Evidence files

GET /v1/accreditations/{accreditationId}/artifacts returns the archived evidence of the process: the company PDFs you uploaded, the identity document captured during biometrics (unico_id_document, typically the ID card as PDF) and, when the provider allows it, the holder selfie (unico_selfie) and the signed evidence-set JWT (unico_evidence_set). Each item already carries a pre-signed downloadUrl, valid for about 10 minutes.

curl -H "Authorization: Bearer $TOKEN" -H "X-Tenant-Id: $TENANT" \
  https://api.corpx.com/v1/accreditations/acr_891418ce2f67/artifacts

{
  "accreditationId": "acr_891418ce2f67",
  "count": 2,
  "items": [
    {
      "artifactId": "art_7c1d90f2ab34",
      "kind": "unico_evidence_set",
      "cpf": "12345678901",
      "fileName": "unico_evidence_set.jwt",
      "contentType": "application/jwt",
      "sizeBytes": 14203,
      "createdAt": "2026-08-15T18:42:03Z",
      "scanStatus": "APPROVED",
      "metadata": { "unicoProcessId": "cst_3bd257e7201d441379256746" },
      "downloadUrl": "https://..."
    }
  ]
}

downloadUrl only shows up with scanStatus: "APPROVED": every upload goes through type checking, antivirus and sanitisation before being archived. While the file is PENDING, query again in a few seconds.

The same files show up in the accreditation detail of your backoffice, for whoever holds the backoffice:accreditations permission (no scope involved there, only the feature).

Next steps

• PF account opening
• PJ account opening
• Returning to your app (callbackUri)
• Onboarding Webhooks