> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# 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**.

> **Enablement**
>
> The onboarding APIs are in controlled rollout. Ask our support team to enable them for your tenant before integrating.

## 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](/baas/guias/abertura-de-contas/pessoa-juridica).
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.).

> **CPF that already has an account**
>
> For PF, if the CPF is already an account holder there is no new account to open. For tenants with **automatic portability enabled** (contractual; not on by default), the accreditation starts as `PENDING_CONSENT` and returns a link for the **holder to authorize** you to operate the account they already have — with identity verification and balance disclosure before the authorization. Without it, the accreditation fails with `existing_partner_account` and portability is requested from support. See [Holder who already has an account](/baas/guias/abertura-de-contas/pessoa-fisica#holder-who-already-has-an-account-consent).

There are **two biometrics flows**:

| Flow                           | How it works                                                                                                                                                                        | Approval                                                               |
| ------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **CorpX biometrics (default)** | We generate a **facial capture link** (powered by Unico) for each person. You deliver the link to the end user, who completes the capture journey in the browser or on their phone. | **PF: automatic** once the facial check is approved. PJ: prior review. |

> **Recommended default**
>
> Deliver the link to the end user and wait for the webhooks. The rest of the journey — capture, validation, account opening — happens on our side.

## State machine

Every accreditation goes through the following state machine:

```mermaid
flowchart TD
  Start["POST /v1/accreditations/pf or /pj"] --> PendingBiometry[PENDING_BIOMETRY]
  Start -->|"PF whose CPF already has an account"| PendingConsent[PENDING_CONSENT]
  PendingConsent -->|"Holder authorizes (identity verified)"| Active[ACTIVE]
  PendingConsent -->|"Declined, expired or identity not confirmed"| Failed[FAILED]
  PendingBiometry -->|"Biometrics approved (all persons)"| BiometryApproved[BIOMETRY_APPROVED]
  PendingBiometry -->|"Rejected or expired"| Failed
  BiometryApproved -->|"PF with CorpX biometrics (automatic)"| Integrating[INTEGRATING]
  BiometryApproved -->|"any PJ (and PF flagged for review)"| PendingReview[PENDING_REVIEW]
  PendingReview -->|"Approved by analyst"| Integrating
  PendingReview -->|"Rejected"| Failed
  Integrating -->|"Account opened at partner"| Active
  Integrating -->|"Rejected by partner"| Failed
```

## Statuses

| Status              | Meaning                                                                                                                                                                                   | Expected integrator action                                                                                                                                                       |
| ------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `PENDING_BIOMETRY`  | Waiting for facial biometrics from one or more persons.                                                                                                                                   | Deliver the facial (or acceptance) link to each pending person. Resend if needed.                                                                                                |
| `PENDING_CONSENT`   | PF only, and only with automatic portability enabled: the CPF **already has an account**, so there is no new account to open — the holder must authorize you to operate the existing one. | Deliver the `consentLink` to the holder. Details in [Holder who already has an account](/baas/guias/abertura-de-contas/pessoa-fisica#holder-who-already-has-an-account-consent). |
| `BIOMETRY_APPROVED` | All biometrics approved. Transitional state.                                                                                                                                              | None — wait for the next webhook.                                                                                                                                                |
| `PENDING_REVIEW`    | Waiting for prior review by an analyst.                                                                                                                                                   | None — wait. Typical turnaround is 1 business day.                                                                                                                               |
| `INTEGRATING`       | Account being opened at the settlement partner. Transitional state.                                                                                                                       | None — wait.                                                                                                                                                                     |
| `ACTIVE`            | Account opened and ready to operate.                                                                                                                                                      | Store the `accountId` and start operating.                                                                                                                                       |
| `FAILED`            | Process ended without opening an account.                                                                                                                                                 | Check `errorReason`. Depending on the reason, retry the biometrics or open a new accreditation with corrected data.                                                              |

## 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](/baas/guias/abertura-de-contas/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](/baas/guias/abertura-de-contas/callback-uri).

## 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](/baas/guias/abertura-de-contas/pessoa-fisica#holder-who-already-has-an-account-consent)). 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.

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

```json
{
  "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.

> **Enablement and scope**
>
> The endpoint delivers the **holder's biometrics**, so it depends on two independent switches:
>
> * the `kyc_artifacts` feature must be enabled for your tenant (talk to support — it requires a contractual clause), otherwise the answer is `403 feature_disabled`;
> * the credential must carry the `kyc.read` scope. The generic `read` scope is deliberately **not** accepted, so no existing credential starts downloading customer faces without an explicit decision.

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).

## Centralized biometry

Some tenants do not use the Unico link or the `biometry` object. Opening an account creates the verification at the tenant's own biometry provider, and the account arrives ready: you do not call the settlement bank.

* Do not send `biometry`. The response is `422 biometry_not_accepted`.
* A company requires exactly one partner with `isAdministrator: true` (`422 administrator_required`). Only that person captures and gets a `biometryLink`; other partners have no link, and retrying them returns `422 administrator_required`.
* Without the tenant's own account at the provider, the verification opens on CorpX's account. Creation only returns `503 kyc_not_configured` when neither is configured.
* The `201` includes `persons[].biometryLink`, the hosted page. When the capture ends it returns to your `callbackUri` with `outcome` (`biometry_approved`, `biometry_pending`, `biometry_failed`, `biometry_expired`), as in CorpX biometry. An app of your own asks for a token at `POST /v1/accreditations/{id}/capture` and relays FaceTec blobs on the public `/start` and `/session` routes. The hosted link, the SDK, how to request the package (bundle id, application id, domains) and which languages are accepted are in the [facial capture guide](/baas/guias/abertura-de-contas/captura-facial). The app does not talk to the provider.
* In this mode a company document goes in `contentBase64` (PDF up to 4 MB) on `POST .../documents`, and only the kinds `company_articles`, `company_proof_of_address` and `financial_statements`. Without the field, `422 document_body_required`; another kind, `422 invalid_kind`; refused by the provider, `422 document_not_accepted`.
* Review, when it happens, is at the provider; the status stays `PENDING_REVIEW` until the decision. Deciding here returns `409 review_in_kyc_provider`.
* `FAILED` carries one of these `errorReason` values: `kyc_rejected`, `kyc_expired`, `kyc_cancelled` (cancelled at the provider), `kyc_misconfigured`, `kyc_unavailable`, `kyc_not_configured`, `document_claimed_elsewhere` (another accreditation for the same document went first), `account_opening_timeout` (identity approved, account did not arrive within 7 days) or `cancelled` (your `POST .../cancel`).

Portability and consent are unchanged: a CPF that already has an account stays on the authorization flow when that flow is enabled.

## Next steps

* [Facial capture (hosted link and FaceTec SDK)](/baas/guias/abertura-de-contas/captura-facial)
* [PF account opening](/baas/guias/abertura-de-contas/pessoa-fisica)
* [PJ account opening](/baas/guias/abertura-de-contas/pessoa-juridica)
* [Returning to your app (`callbackUri`)](/baas/guias/abertura-de-contas/callback-uri)
* [Onboarding Webhooks](/baas/guias/abertura-de-contas/webhooks)