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

Step 1: Create the accreditation

Request

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.
`partners[].biometry`	object	No	Only for the Bring Your Own biometrics flow.
`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.

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)

{
  "accreditationId": "acr_1a2b3c4d5e6f",
  "type": "pj",
  "status": "PENDING_BIOMETRY",
  "legalForm": "ltda",
  "requiredDocumentKinds": ["company_articles", "company_proof_of_address"],
  "missingDocumentKinds": ["company_articles", "company_proof_of_address"],
  "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; fileName required.
Document freshness (e.g. proof of address) is checked by the operator during prior review.

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"
  }'

The response includes uploadUrl (PUT, 1h). Repeat for each required kind. The accreditation GET shows documents[] and missingDocumentKinds[].

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 and shows up as rejected in the operator review; 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:

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:

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

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.

Flow​

Step 1: Create the accreditation​

Request​

Parameters​

Response (201)​

Step 2: Upload company PDFs​

Step 3: Deliver a link to each partner​

Step 4: Prior review​

Step 5: Account ready​

Per-partner retry​

Cancel​

Querying​