> 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 Opening — Companies (PJ)

This guide walks through opening a company account. The difference from PF: facial biometrics are required from **every partner** (or statutory director, for cooperatives), you must upload the **company PDFs** required for the company type, and every PJ opening goes through **prior review** by an analyst before the account is opened.

## Flow

```mermaid
sequenceDiagram
  participant You as Your system
  participant API as CorpX API
  participant Partners as Partners (end users)
  participant Analyst as Analyst
  participant Bank as Settlement partner

  You->>API: POST /v1/accreditations/pj
  API-->>You: 201 accreditationId + biometryLinks + missingDocumentKinds
  You->>API: POST /accreditations/id/documents (required PDFs)
  You->>Partners: Deliver the link to each partner
  Partners->>API: Each partner completes the facial capture
  Note over API: Waits for approved partners (docs in parallel)
  API-->>You: webhook accreditation.updated (PENDING_REVIEW)
  Analyst->>API: Prior review and approval
  API-->>You: webhook accreditation.updated (INTEGRATING)
  API->>Bank: Opens the account
  Bank-->>API: Account created
  API-->>You: webhook accreditation.active (accountId ready)
```

## Step 1: Create the accreditation

### Request

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/pj" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: onboard-company-9876" \
  -d '{
    "company": {
      "legalName": "Empresa Exemplo LTDA",
      "tradeName": "Exemplo",
      "cnpj": "12345678000199",
      "email": "financeiro@exemplo.com",
      "phone": "+5511333334444",
      "monthlyRevenue": 150000.00,
      "legalForm": "ltda"
    },
    "address": {
      "zipCode": "01310100",
      "street": "Avenida Paulista",
      "number": "1000",
      "complement": "Conjunto 101",
      "neighborhood": "Bela Vista",
      "city": "São Paulo",
      "state": "SP",
      "cityIbgeCode": "3550308"
    },
    "partners": [
      {
        "name": "João Souza",
        "cpf": "11122233344",
        "birthDate": "1985-03-10",
        "email": "joao@exemplo.com",
        "phone": "+5511988887777",
        "ownershipPercent": 60,
        "isAdministrator": true
      },
      {
        "name": "Ana Lima",
        "cpf": "55566677788",
        "birthDate": "1992-11-02",
        "email": "ana@exemplo.com",
        "phone": "+5511977776666",
        "ownershipPercent": 40,
        "isAdministrator": false
      }
    ]
  }'
```

### Parameters

| Field                                   | Type    | Required | Description                                                                                                                                                                                                             |
| --------------------------------------- | ------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `company.legalName`                     | string  | Yes      | Legal name.                                                                                                                                                                                                             |
| `company.tradeName`                     | string  | **Yes**  | Trade name. The banking provider requires this field for a CNPJ. If the company has no registered trade name, repeat the legal name.                                                                                    |
| `company.cnpj`                          | string  | Yes      | CNPJ (14 digits, no punctuation).                                                                                                                                                                                       |
| `company.email` / `company.phone`       | string  | Yes      | Company contact.                                                                                                                                                                                                        |
| `company.monthlyRevenue`                | number  | No       | Declared monthly revenue (BRL).                                                                                                                                                                                         |
| `company.legalForm`                     | string  | No       | Company type: `mei`, `ltda` (default), `sa`, `cooperative`. Drives required PDFs.                                                                                                                                       |
| `address.*`                             | object  | Yes      | Company address. `neighborhood` is **required** (or legacy `district`). `cityIbgeCode` with **7 digits** (IBGE code).                                                                                                   |
| `partners[]`                            | array   | Yes      | Ownership structure (or **statutory directors** if `legalForm=cooperative`). **At least one** with `isAdministrator: true`.                                                                                             |
| `partners[].name` / `cpf` / `birthDate` | —       | Yes      | Each partner/director's data. Facial biometrics will be required from **all of them**.                                                                                                                                  |
| `partners[].email` / `phone`            | string  | Yes      | Contact — used for the biometrics journey.                                                                                                                                                                              |
| `partners[].ownershipPercent`           | number  | Yes      | Ownership share (%).                                                                                                                                                                                                    |
| `partners[].isAdministrator`            | boolean | Yes      | Whether the partner/director is an administrator. **At least one** administrator is required; more than one is accepted. With none, the `POST` is rejected with `400 invalid_payload` and no biometrics link is issued. |
| `callbackUri`                           | string  | No       | Where to take each partner back to once they complete the biometrics. Requires prior registration with support — see [Returning to your app](/baas/guias/abertura-de-contas/callback-uri).                              |

Initial PIX limits are applied automatically with conservative defaults. Limit changes (increase or decrease) require a manual request to support.

> **Cooperative**
>
> With `legalForm=cooperative`, list in `partners[]` the **statutory directors** (not the full member roster). Required documents match `sa`.

### Response (201)

```json
{
  "accreditationId": "acr_1a2b3c4d5e6f",
  "type": "pj",
  "status": "PENDING_BIOMETRY",
  "legalForm": "ltda",
  "requiredDocumentKinds": ["company_articles"],
  "missingDocumentKinds": ["company_articles"],
  "documents": [],
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "11122233344",
      "name": "João Souza",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc111...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    },
    {
      "personId": "prs_8d2f4e6a1c0b",
      "cpf": "55566677788",
      "name": "Ana Lima",
      "biometryStatus": "PENDING",
      "biometryLink": "https://cadastro.unico.app/process/abc222...",
      "linkExpiresAt": "2026-07-14T18:00:00Z"
    }
  ],
  "createdAt": "2026-07-07T18:00:00Z"
}
```

> **Account not bound yet**
>
> While `PENDING_BIOMETRY`, the CNPJ is **not** bound to the tenant and `POST` **does not deduplicate** — repeating with the same CNPJ creates another accreditation. Cancel abandoned pendings with `POST /v1/accreditations/{id}/cancel`.

> **Asynchronous links**
>
> The `biometryLink` values are issued within seconds, but **asynchronously** — they may be absent from the `POST` response. When that happens, receive each one via the `accreditation.biometry.link.created` webhook (emitted per partner) or call the `GET` right after.

## Step 2: Upload company PDFs

After the `201`, upload the PDFs required for the `legalForm` (always `application/pdf`):

| legalForm           | Required                                       | Optional                                                                      |
| ------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------- |
| `mei`, `ltda`       | `company_articles`                             | `company_proof_of_address`, `business_license`, `regulatory_license`, `other` |
| `sa`, `cooperative` | LTDA set + `cnpj_card`, `financial_statements` | same                                                                          |

* Typed kinds: **one** per accreditation (re-upload replaces).
* `other`: multiple files (**10** max); `fileName` required.
* Document freshness (e.g. proof of address) is checked by the **operator** during prior review.

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/documents" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "company_articles",
    "fileName": "articles-of-association.pdf",
    "contentType": "application/pdf",
    "sizeBytes": 184320
  }'
```

The response includes `uploadUrl` (PUT, 1h). **`sizeBytes` is the file's actual size** and is part of the signature: the PUT must send exactly that many bytes, with no CorpX auth header. Repeat for each required kind.

The `201` **does not fulfil the requirement**. The accreditation `GET` lists the slot in `documents[]` with `deliveryStatus: pending_upload` and keeps the kind in `missingDocumentKinds` until the object exists in the archive (size > 0) and, when the pipeline is on, passes the scan. Only then does `deliveryStatus` become `delivered` and `uploadedAt` appear.

After the `PUT`, the file goes through antivirus and sanitization (the PDF is rasterized) before being archived — this takes a few seconds. A file that is not really a PDF, or that is infected or corrupted, is rejected (`deliveryStatus: rejected`); upload it again with the correct file.

## Step 3: Deliver a link to each partner

Each partner receives **their own** `biometryLink` and must complete the journey individually. The accreditation enters review when **all** partners have approved biometrics (PDFs can be uploaded in parallel).

* Each link expires in 7 days — track `linkExpiresAt` per person.
* The `accreditation.biometry.link.created` event is emitted once **per partner**.
* Pending partners show up with `biometryStatus: "PENDING"` on the `GET`.

## Step 4: Prior review

With **all biometrics approved**, the accreditation enters `PENDING_REVIEW` — **every PJ goes through prior review**. Ideally required PDFs are already uploaded (`missingDocumentKinds` empty); the analyst sees gaps on the detail. You receive `accreditation.updated` when entering and leaving this stage. Typical turnaround is 1 business day.

* **Approved** (docs complete) → `INTEGRATING` and the account is opened at the settlement partner.
* **Approved with override** — if PDFs are still missing, the operator can force with `forceIncompleteDocuments: true` + `reason`; recorded as `documentsOverride*` on the accreditation.
* **Rejected** → status changes to `FAILED` with `errorReason` explaining why.

## Step 5: Account ready

When the account is opened you receive `accreditation.active`. The `accountId` is bound to your tenant and ready to operate.

## Per-partner retry

If a partner's link expired or their capture failed, generate a new link **only for that partner** — the others are not affected:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/persons/55566677788/retry" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"
```

## Cancel

While status is `PENDING_BIOMETRY`, you can cancel the whole accreditation:

```bash
curl -X POST "https://tenant.api.corpx.com/v1/accreditations/acr_1a2b3c4d5e6f/cancel" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany" \
  -H "Content-Type: application/json" \
  -d '{"reason":"company abandoned onboarding"}'
```

## Querying

```bash
curl -X GET "https://tenant.api.corpx.com/v1/accreditations/pj?document=12345678000199" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"
```

The response carries the aggregated status and per-partner details (`biometryStatus`, link and expiration for each one), letting you build a tracking screen in your system.