Create company accreditation (Pessoa Jurídica)

curl -X POST https://tenant.api.corpx.com/v1/accreditations/pj \
     -H "X-Tenant-Id: X-Tenant-Id" \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "company": {
    "legalName": "MARIA DA SILVA",
    "tradeName": "MARIA DA SILVA",
    "cnpj": "12345678000190",
    "email": "maria.silva@example.com",
    "phone": "+5511999999999",
    "monthlyRevenue": 150.75,
    "legalForm": "ltda"
  },
  "address": {
    "zipCode": "01310100",
    "street": "Avenida Paulista",
    "number": "1000",
    "city": "São Paulo",
    "state": "SP",
    "cityIbgeCode": "3550308",
    "complement": "Sala 501",
    "neighborhood": "Centro"
  },
  "partners": [
    {
      "name": "MARIA DA SILVA",
      "cpf": "12345678900",
      "birthDate": "2026-02-20",
      "email": "maria.silva@example.com",
      "phone": "+5511999999999",
      "ownershipPercent": 50,
      "isAdministrator": true,
      "biometry": {
        "provider": "unico",
        "evidenceId": "8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
        "metadata": {}
      }
    }
  ],
  "callbackUri": "https://app.yourcompany.com/onboarding/done"
}'

{
  "accreditationId": "acr_9f8e7d6c5b4a",
  "accountId": "2e6b725b-84a0-400d-8740-22a5ba0f23e6",
  "type": "pf",
  "document": "12345678900",
  "status": "PENDING_BIOMETRY",
  "biometryMode": "unico",
  "legalForm": "mei",
  "documents": [
    {
      "documentId": "8c1f6a2e-4d3b-4b9a-9f0e-1a2b3c4d5e6f",
      "kind": "company_articles",
      "fileName": "MARIA DA SILVA",
      "deliveryStatus": "pending_upload",
      "uploadedAt": "2026-02-20T08:33:39Z",
      "sizeBytes": 50
    }
  ],
  "requiredDocumentKinds": [
    "company_articles"
  ],
  "missingDocumentKinds": [
    "company_articles"
  ],
  "documentsOverride": true,
  "documentsOverrideBy": "12345678900",
  "documentsOverrideReason": "12345678900",
  "documentsOverrideMissing": [
    "12345678900"
  ],
  "documentsOverrideAt": "2026-02-20T08:33:39Z",
  "callbackUri": "https://app.yourcompany.com/onboarding/done",
  "persons": [
    {
      "personId": "prs_3b1c9a7f2e4d",
      "cpf": "12345678900",
      "name": "MARIA DA SILVA",
      "biometryStatus": "PENDING",
      "biometryLink": "https://onboarding.corpx.com/c/8c1f6a2e",
      "acceptanceStatus": "COMPLETED",
      "acceptanceLink": "https://onboarding.corpx.com/c/8c1f6a2e",
      "consentStatus": "PENDING",
      "consentLink": "https://onboarding.corpx.com/c/8c1f6a2e",
      "consentExpiresAt": "2026-02-20T08:33:39Z",
      "linkExpiresAt": "2026-02-20T08:33:39Z"
    }
  ],
  "partner": {
    "code": "request.body.invalid",
    "message": "A solicitação é inválida: O número não pode exceder 10 caracteres.",
    "field": "address.number"
  },
  "createdAt": "2026-02-20T08:33:39Z",
  "updatedAt": "2026-02-20T08:33:39Z"
}

Opens a company (PJ) account. Every partner listed in partners[] receives an individual facial-biometrics link (default flow) or an acceptance link (external biometrics flow, partners[].biometry). After create, upload the required company PDFs via POST /v1/accreditations/{id}/documents (see company.legalForm). The account moves to PENDING_REVIEW after ALL partners complete biometrics; a CorpX operator must then approve (mandatory for PJ). Approve with missing required PDFs needs forceIncompleteDocuments=true + reason (audited).

For legalForm=cooperative, partners[] are the statutory directors (diretores estatutários), not cooperative members.

At least one partner must have isAdministrator: true. More than one administrator is accepted. With none, the POST is refused here with 400 invalid_payload and no biometrics link is issued. The number of partners is not limited.

company.tradeName is required. The banking provider rejects a CNPJ without a trade name, so an empty value is refused at creation with 400 missing_fields instead of failing at the end of the journey. If the company has no registered trade name, repeat the legal name.

Does not deduplicate. While status is PENDING_BIOMETRY, repeating POST with the same CNPJ creates another accreditation (201). After biometry is confirmed, a further POST for a document already claimed by the tenant returns 409 already_accredited. Cancel abandoned pendings with POST /v1/accreditations/{id}/cancel. BaaS integrators only.

Sending each partner back to your app. The optional callbackUri takes each partner back to your app when they finish their own facial capture, carrying personId and how many partners are still pending in remainingPeople. It requires the URI to be registered for your tenant beforehand — an unregistered URI returns 400 invalid_callback_uri.

Opens a company (PJ) account. Every partner listed in `partners[]` receives an individual facial-biometrics link (default flow) or an acceptance link (external biometrics flow, `partners[].biometry`). After create, upload the required company PDFs via `POST /v1/accreditations/{id}/documents` (see `company.legalForm`). The account moves to `PENDING_REVIEW` after ALL partners complete biometrics; a CorpX operator must then approve (mandatory for PJ). Approve with missing required PDFs needs `forceIncompleteDocuments=true` + `reason` (audited). For `legalForm=cooperative`, `partners[]` are the **statutory directors** (diretores estatutários), not cooperative members. **At least one partner must have `isAdministrator: true`.** More than one administrator is accepted. With none, the `POST` is refused here with `400 invalid_payload` and no biometrics link is issued. The number of partners is not limited. **`company.tradeName` is required.** The banking provider rejects a CNPJ without a trade name, so an empty value is refused at creation with `400 missing_fields` instead of failing at the end of the journey. If the company has no registered trade name, repeat the legal name. **Does not deduplicate.** While status is `PENDING_BIOMETRY`, repeating `POST` with the same CNPJ creates another accreditation (`201`). After biometry is confirmed, a further `POST` for a document already claimed by the tenant returns `409 already_accredited`. Cancel abandoned pendings with `POST /v1/accreditations/{id}/cancel`. **BaaS integrators only.** **Sending each partner back to your app.** The optional `callbackUri` takes each partner back to your app when they finish their own facial capture, carrying `personId` and how many partners are still pending in `remainingPeople`. It requires the URI to be registered for your tenant beforehand — an unregistered URI returns `400 invalid_callback_uri`.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

companyobjectRequired

addressobjectRequired

Holder/company address. cityIbgeCode is the 7-digit IBGE municipality code.

partnerslist of objectsRequired

callbackUristringOptional

Optional. Where to send the account holder back to when the step is finished (facial capture, terms acceptance or portability authorization). Without it the holder ends on a CorpX completion page, as before.

The URI must be registered for your tenant by CorpX support before the first use, and the match is exact — no wildcards, no prefix matching. An unregistered URI is rejected at creation time with 400 invalid_callback_uri.

Accepted: https:// and your application’s own scheme (deeplink). Rejected: http://, javascript:, data:, file:, credentials in the URI, fragments (#), localhost, private/link-local IP ranges and internal suffixes (.local, .internal).

On return, CorpX appends accreditationId, outcome, personId (for per-person steps) and remainingPeople (when the accreditation has more than one person). These parameters are not proof of anything: they travel in the address bar and the holder can edit them. Any decision with an effect must rely on the webhook or on GET /v1/accreditations/{accreditationId}.

Response

Accreditation created; per-partner links are being issued.

accreditationIdstringOptional

accountIdstringOptional

Account id — usable in all banking endpoints once status is ACTIVE.

typeenumOptional

documentstringOptional

statusenumOptional

Accreditation lifecycle status.

biometryModeenumOptional

unico = CorpX-managed facial biometrics (default); external = provider enabled by CorpX on request.

legalFormenumOptional

PJ only — corporate form from create.

documentslist of objectsOptional

PJ only — uploaded company PDFs.

requiredDocumentKindslist of enumsOptional

PJ only — kinds required for this legalForm (operator approve gate).

missingDocumentKindslist of enumsOptional

PJ only — required kinds not yet uploaded.

documentsOverridebooleanOptional

true when an operator forced approve with incomplete docs.

documentsOverrideBystringOptional

documentsOverrideReasonstringOptional

documentsOverrideMissinglist of stringsOptional

documentsOverrideAtdatetimeOptional

callbackUristringOptional

personslist of objectsOptional

errorReasonstringOptional

errorMessagestringOptional

partnerobjectOptional

Raw refusal from the banking provider, present only when a FAILED accreditation was refused by it. It is the same block delivered in the accreditation.failed webhook — the query never shows less than the webhook. All three keys are optional: the block mirrors what the provider sent, and some refusals carry message only. Informative — branch your code on errorReason, not on this.

createdAtdatetimeOptional

updatedAtdatetimeOptional

Errors

400

Bad Request Error

409

Conflict Error

422

Unprocessable Entity Error

500

Internal Server Error

For legalForm=cooperative, partners[] are the statutory directors (diretores estatutários), not cooperative members.

Authentication

Headers

Request

Response

Errors