Create company accreditation (Pessoa Jurídica)
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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Headers
Optional client-generated idempotency token (recommended for safe retries).
Request
Holder/company address. cityIbgeCode is the 7-digit IBGE municipality code.
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.
Account id — usable in all banking endpoints once status is ACTIVE.
unico = CorpX-managed facial biometrics (default); external = provider enabled by CorpX on request.
PJ only — corporate form from create.
PJ only — uploaded company PDFs.
PJ only — kinds required for this legalForm (operator approve gate).
PJ only — required kinds not yet uploaded.
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}.
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. code, message and field are the item the
catalog recognized, or message alone when none of the provider’s
codes was recognized. errors lists every item the provider sent,
in its order, with the same three keys. Every key is optional:
some refusals carry message only, and an accreditation refused
before errors existed has no list. Informative — branch your
code on errorReason, not on this.