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

# Onboarding Webhooks

All onboarding events follow the platform's [standard webhook envelope](/baas/guias/conta/webhooks) (same delivery format, authentication, retries and idempotency). This page documents the accreditation-specific events.

## Events

| Event                                   | When it is emitted                                                                                    |
| --------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `accreditation.pf.created`              | A PF accreditation was created.                                                                       |
| `accreditation.pj.created`              | A PJ accreditation was created.                                                                       |
| `accreditation.biometry.link.created`   | A facial capture link was generated for a person (emitted per person; re-emitted on retry).           |
| `accreditation.acceptance.link.created` | A terms acceptance link was generated for a person (only in flows enabled on request by CorpX).       |
| `accreditation.consent.link.created`    | An authorization link was generated because the CPF **already has an account** (re-emitted on retry). |
| `account.shared_access.granted`         | Another tenant started operating an account **you already operated**, authorized by the holder.       |
| `accreditation.updated`                 | **Every state transition** of the accreditation. Source of truth for progress.                        |
| `accreditation.active`                  | Account opened successfully — `accountId` ready to operate.                                           |
| `accreditation.failed`                  | Process ended without opening an account.                                                             |

> **Recommendation**
>
> Subscribe to `accreditation.updated` as the source of truth for progress, and use `accreditation.active` / `accreditation.failed` as terminal triggers in your system. The link events are meant to automate delivering links to end users.

> **\`callbackUri\` does not replace these events**
>
> If you use the [return to your app](/baas/guias/abertura-de-contas/callback-uri), the `outcome` that arrives in the URI is a **UI hint**: it travels in the address bar and the holder can edit it. Use it only to decide which screen to show when the user comes back. Every trigger with an effect in your system still comes from here — or from `GET /v1/accreditations/{accreditationId}`.

## `accreditation.updated`

Emitted on **every state transition**, with the previous status, the current one and per-person details.

```json
{
  "id": "evt_acr_upd_001",
  "type": "accreditation.updated",
  "occurredAt": "2026-07-07T18:20:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "previousStatus": "PENDING_BIOMETRY",
    "status": "INTEGRATING",
    "persons": [
      {
        "cpf": "12345678901",
        "name": "Maria da Silva",
        "biometryStatus": "APPROVED"
      }
    ]
  }
}
```

| `data` field                | Description                                                                                                                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `accreditationId`           | Accreditation ID.                                                                                                                                                                      |
| `type`                      | `pf` or `pj`.                                                                                                                                                                          |
| `document`                  | Holder's CPF (PF) or CNPJ (PJ).                                                                                                                                                        |
| `previousStatus` / `status` | State transition (vocabulary from the [Overview](/baas/guias/abertura-de-contas/visao-geral#statuses)).                                                                                |
| `persons[]`                 | Per-person details: `cpf`, `name`, `biometryStatus` (`PENDING`, `APPROVED`, `FAILED`, `EXPIRED`) and, when a terms acceptance is involved, `acceptanceStatus` (`PENDING`, `ACCEPTED`). |
| `errorReason`               | Present when `status = FAILED`.                                                                                                                                                        |

## `accreditation.biometry.link.created`

Emitted when a facial capture link is generated for a person (at accreditation creation and on each retry).

```json
{
  "id": "evt_acr_link_001",
  "type": "accreditation.biometry.link.created",
  "occurredAt": "2026-07-07T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "biometryLink": "https://cadastro.unico.app/process/abc123...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}
```

For PJ, this event is emitted **once per partner** — use the `cpf` to know who each link belongs to.

## `accreditation.acceptance.link.created`

Emitted when a terms acceptance link is generated for a person. Only happens in flows enabled on request by CorpX; the default flow never emits it.

```json
{
  "id": "evt_acr_acc_001",
  "type": "accreditation.acceptance.link.created",
  "occurredAt": "2026-07-07T18:05:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "acceptanceLink": "https://tenant.api.corpx.com/v1/accreditations/accept/tok_...",
    "linkExpiresAt": "2026-07-14T18:00:00Z"
  }
}
```

## `accreditation.consent.link.created`

Emitted when the CPF **already has an account** and the accreditation starts as `PENDING_CONSENT`: instead of opening a new account, the holder must authorize you to operate the existing one. Deliver the `consentLink` to them. Re-emitted on every retry.

```json
{
  "id": "acr-acr_5c4b3a2f1e0d-consent-12345678901-1",
  "type": "accreditation.consent.link.created",
  "occurredAt": "2026-07-23T18:00:05.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_5c4b3a2f1e0d",
    "type": "pf",
    "cpf": "12345678901",
    "name": "Maria da Silva",
    "consentId": "cns_8f2a1c9d4b70",
    "consentLink": "https://tenant.api.corpx.com/v1/accreditations/consent/cst_...",
    "linkExpiresAt": "2026-07-30T18:00:00Z",
    "status": "PENDING_CONSENT"
  }
}
```

Journey details in [Holder who already has an account](/baas/guias/abertura-de-contas/pessoa-fisica#holder-who-already-has-an-account-consent).

## `accreditation.active`

Terminal success event — the account is ready to operate.

```json
{
  "id": "evt_acr_active_001",
  "type": "accreditation.active",
  "occurredAt": "2026-07-07T18:25:41.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "ACTIVE",
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8"
  }
}
```

When the accreditation came from the consent flow, `data` carries two extra fields:

| `data` field       | Description                                                                                                                                   |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `sharedAccount`    | `true` — the account **already existed** and remains operated by whoever the holder had already authorized. Balance and statement are shared. |
| `partnerAccountId` | Holder identifier at the settlement partner, common to every authorized tenant. Useful for reconciliation.                                    |

## `account.shared_access.granted`

Emitted to the tenants that **already operated** an account when the holder authorizes a new tenant to operate it too. Your access does not change — this event exists so that you know the account is now being moved by someone else as well.

```json
{
  "id": "acr-acr_5c4b3a2f1e0d-shared-tenant-acme",
  "type": "account.shared_access.granted",
  "occurredAt": "2026-07-23T18:40:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
    "tenantId": "tenant-acme",
    "partnerAccountId": "hld_7c1e...",
    "grantedAt": "2026-07-23T18:40:00Z",
    "reason": "account_holder_authorized_another_tenant"
  }
}
```

| `data` field       | Description                                                                               |
| ------------------ | ----------------------------------------------------------------------------------------- |
| `accountId`        | **Your** account (the identifier you already use), not the one of the tenant that joined. |
| `partnerAccountId` | Holder at the settlement partner — this is what evidences it is the same account.         |
| `grantedAt`        | Moment of the holder's authorization.                                                     |
| `reason`           | `account_holder_authorized_another_tenant`.                                               |

> **Don't recognize it?**
>
> If the sharing does not make sense for your case, contact support: the holder can revoke the granted access, and from then on the revoked tenant's calls for that account return `403`.

## `accreditation.failed`

Terminal failure event — the process ended without opening an account.

```json
{
  "id": "evt_acr_failed_001",
  "type": "accreditation.failed",
  "occurredAt": "2026-07-08T10:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "accountId": "c283eb5a-58da-47ef-844a-f36e51f078d8",
  "data": {
    "accreditationId": "acr_9f8e7d6c5b4a",
    "type": "pf",
    "document": "12345678901",
    "status": "FAILED",
    "errorReason": "biometry_expired",
    "errorMessage": "Facial biometrics not completed within the 7-day deadline"
  }
}
```

Common `errorReason` values:

| `errorReason`                | Meaning                                                                                                                                                                                                                                                                       |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `biometry_failed`            | Facial biometrics rejected.                                                                                                                                                                                                                                                   |
| `biometry_expired`           | Facial link expired without completion.                                                                                                                                                                                                                                       |
| `evidence_invalid`           | External biometrics evidence not validated with the partner (flows enabled on request).                                                                                                                                                                                       |
| `acceptance_timeout`         | Acceptance term not confirmed in time (flows enabled on request).                                                                                                                                                                                                             |
| `cancelled`                  | Cancelled by the integrator via `POST /v1/accreditations/{id}/cancel` (still `PENDING_BIOMETRY` or `PENDING_CONSENT`).                                                                                                                                                        |
| `review_rejected`            | Rejected during prior review.                                                                                                                                                                                                                                                 |
| `partner_rejected`           | Rejected by the settlement partner during account opening.                                                                                                                                                                                                                    |
| `partner_validation_failed`  | The provider rejected a registration value. See the `partner` block below.                                                                                                                                                                                                    |
| `partner_unavailable`        | Provider outage. Transient: resend the accreditation.                                                                                                                                                                                                                         |
| `consent_declined`           | The holder **declined** to authorize access to the account they already had.                                                                                                                                                                                                  |
| `consent_expired`            | The holder did not complete the authorization in time (7-day link, 30-day journey).                                                                                                                                                                                           |
| `consent_facial_failed`      | The identity verification did not confirm the person as the CPF holder.                                                                                                                                                                                                       |
| `consent_link_failed`        | The authorization could not be prepared or completed (e.g. holder data diverged between the request and the authorization). Contact support.                                                                                                                                  |
| `castle_deny`                | The device risk assessment blocked the acceptance — both on the acceptance term and on the portability authorization. Contact support.                                                                                                                                        |
| `existing_partner_account`   | CPF/CNPJ that **already has an account**. Portability is manual: the holder must request it from support. For PF, if your tenant has automatic portability enabled, this reason does not occur — the path is the `consentLink`. There is no hosted authorization flow for PJ. |
| `kyc_rejected`               | Centralized biometry only: the tenant's KYC refused the identity verification.                                                                                                                                                                                                |
| `kyc_expired`                | Centralized biometry only: the capture was not completed within 7 days.                                                                                                                                                                                                       |
| `kyc_cancelled`              | Centralized biometry only: the verification was cancelled at the provider.                                                                                                                                                                                                    |
| `kyc_misconfigured`          | Centralized biometry only: the tenant's KYC preset does not ask for facial biometry. Contact support.                                                                                                                                                                         |
| `kyc_unavailable`            | Centralized biometry only: the provider did not open the verification. Create a new accreditation.                                                                                                                                                                            |
| `kyc_not_configured`         | Centralized biometry only: neither the tenant nor CorpX had an account configured at the provider when the verification was opened. Contact support.                                                                                                                          |
| `document_claimed_elsewhere` | Another accreditation for the same document went ahead first.                                                                                                                                                                                                                 |
| `account_opening_timeout`    | Centralized biometry only: identity approved, but the account did not arrive within 7 days. Contact support.                                                                                                                                                                  |

When the refusal comes from the provider, `data` also carries a `partner` block
with what it reported — the **same** block is returned by
`GET /v1/accreditations/{id}`, so the query and the webhook never disagree:

```json
"partner": {
  "code": "request.body.invalid",
  "field": "address.number",
  "message": "A solicitação é inválida: O número não pode exceder 10 caracteres.",
  "errors": [
    {
      "code": "request.body.invalid",
      "field": "address.number",
      "message": "A solicitação é inválida: O número não pode exceder 10 caracteres."
    }
  ]
}
```

`code`, `message` and `field` are the item we recognized — or `message` alone,
when none of the provider's codes is known. `errors` lists every item the
provider sent, in its order, with the same three keys. Every key is optional:
some refusals arrive with `message` only, and an accreditation refused before
`errors` existed has no list. Use the block for logs and support — your code
should still branch on `errorReason`.

## `accreditation.pf.created` / `accreditation.pj.created`

Emitted when the accreditation is created (workflow start), as an asynchronous confirmation of the `POST`. Subscribe in the portal (**Settings → Webhooks**) or via `PUT` on the subscription.

```json
{
  "id": "acr-acr_1a2b3c4d5e6f-created",
  "type": "accreditation.pj.created",
  "occurredAt": "2026-07-07T18:00:00.000Z",
  "schemaVersion": "1.0",
  "environment": "production",
  "tenantId": "tenant-acme",
  "data": {
    "accreditationId": "acr_1a2b3c4d5e6f",
    "type": "pj",
    "document": "12345678000199",
    "status": "PENDING_BIOMETRY",
    "biometryMode": "external"
  }
}
```