Create individual accreditation (Pessoa Física)
Opens an individual (PF) account. By default CorpX generates a Unico
facial-biometrics link (persons[].biometryLink) that you deliver to
the end user; the account is opened automatically once the biometrics
is approved. Tenants with an external biometrics provider enabled by
CorpX on request may instead send the person.biometry object.
CPF that already has an account. When the CPF is already an account holder there is no new account to open, and the outcome depends on whether automatic portability is enabled for the tenant (contractual, off by default — talk to CorpX to enable it).
With portability enabled, the response comes back with
status: PENDING_CONSENT and persons[].consentLink instead of
biometryLink: deliver that link to the account holder, who authorizes
this tenant to operate the existing account after an identity
verification (live selfie checked against official records by CPF) and
after seeing the account number and current balance. On authorization
you receive accreditation.active with sharedAccount: true — the same
account, same balance, and every previously authorized tenant keeps its
access. Rejection, expiry or a failed identity check end the
accreditation as FAILED with a consent_* reason.
Without portability enabled, no consentLink is issued: the
accreditation ends as FAILED with errorReason=existing_partner_account
and a message instructing the holder to request portability from
support, which handles it manually.
Does not deduplicate. While status is PENDING_BIOMETRY or
PENDING_CONSENT, repeating POST with the same CPF 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 the holder back to your app. The optional callbackUri
takes the holder back to your app or site when the step is finished,
with the outcome in the URI itself. 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. Biometrics/acceptance links are being issued,
or — when the CPF already has an account — status is
PENDING_CONSENT and persons[].consentLink carries the
authorization page for the account holder.
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.