Register PIX key

Registers a new PIX key after validating the request, enforcing owner limits, and successfully synchronizing with BACEN DICT. Registration fails closed if BACEN DICT is unavailable or rejects the key.

POST /api/v1/dict/keys

Register PIX key

cURL

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/keys \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Idempotency: <x-idempotency>' \
  --data '
{
  "accountNumber": "9988776",
  "accountType": "CACC",
  "keyType": "CPF",
  "openingDate": "2020-01-15T00:00:00Z",
  "ownerName": "João Silva",
  "ownerTaxId": "12345678901",
  "participantISPB": "12345678",
  "reason": "USER_REQUESTED",
  "requestId": "b2696bf1-0a51-48b0-ab4a-8af2dff440af",
  "branch": "0001",
  "keyValue": "12345678901",
  "ownerTradeName": "Silva ME",
  "ownerType": "NATURAL_PERSON"
}
'

201

{
  "createdAt": "2025-03-07T14:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "keyType": "CPF",
  "keyValue": "12345678901",
  "ownerName": "João Silva",
  "ownerTaxId": "12345678901",
  "participantISPB": "12345678",
  "status": "ACTIVE",
  "updatedAt": "2025-03-07T14:30:00Z",
  "accountNumber": "9988776",
  "accountType": "CACC",
  "bacen": {
    "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "lastModified": "2026-06-14T12:00:00Z",
    "responseTime": "2026-06-14T12:00:00Z"
  },
  "branch": "0001",
  "creationDate": "2020-01-15T00:00:00Z",
  "keyOwnershipDate": "2020-01-15T00:00:00Z",
  "openingDate": "2020-01-15T00:00:00Z",
  "ownerTradeName": "Silva ME",
  "ownerType": "NATURAL_PERSON",
  "requestId": "b2696bf1-0a51-48b0-ab4a-8af2dff440af"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

Idempotency key, max 255 characters

Body

application/json

PIX key to register (key type, value, owner identity, and participant ISPB); registration fails closed if BACEN DICT rejects or is unavailable

accountNumber · string · required

Account number, 1 to 20 digits. BACEN admits letters here; this rail does not, and the door states the narrower rule it actually applies.

Pattern: ^[0-9]{1,20}$

Example:

"9988776"

accountType · enum<string> · required

BACEN account type: CACC (current), SVGS (savings), TRAN (transactional), SLRY (salary), or OTHR (other).

Available options: CACC, SVGS, TRAN, SLRY, OTHR

Example:

"CACC"

keyType · enum<string> · required

PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP (random key).

Available options: CPF, CNPJ, EMAIL, PHONE, EVP

Example:

"CPF"

openingDate · string<date-time> · required

Account opening date, RFC 3339 (the FI account's opening date, not the key's creation moment).

Example:

"2020-01-15T00:00:00Z"

ownerName · string · required

Full legal name of the key owner (at most 150 characters). The accepted character set differs by owner type — letters, apostrophe, hyphen and space for an individual; printable Latin-1 for a company — and is applied by the service, since one schema pattern cannot depend on the tax id's length.

Required string length: 1 - 150

Example:

"João Silva"

ownerTaxId · string · required

Owner tax identifier: 11 digits for a CPF (individuals), 14 alphanumeric characters for a CNPJ (businesses, IN RFB 2.229/2024). Shaped as the SPI wire type PICpfCnpj. The check digits are verified by the service.

Pattern: ^([0-9]{11}|[0-9A-Z]{12}[0-9]{2})$

Example:

"12345678901"

participantISPB · string · required

Owning participant ISPB, the 8-digit BACEN institution identifier.

Pattern: ^[0-9]{8}$

Example:

"12345678"

reason · enum<string> · required

Why this key is being registered, sent verbatim to BACEN as createEntry's Reason. USER_REQUESTED when an end user asked for the key, RECONCILIATION when restoring a binding this PSP already holds after a divergence. Required: only the participant holds the fact that decides it, so there is no default.

Available options: USER_REQUESTED, RECONCILIATION

Example:

"USER_REQUESTED"

requestId · string<uuid> · required

Idempotency key for this registration, a version 4 UUID, sent verbatim to BACEN as createEntry's RequestId. Required — never invented here. BACEN binds it to the vinculo for life and refuses a reuse under different binding parameters, so send a fresh value per registration. This rail does not refuse a reused value locally: the rule is BACEN's, enforced there and relayed. Must be version 4: every other version derives from a clock, a node id or a hashed name, so two different registrations can collide by construction. Distinct from the X-Idempotency header, which is this rail's own de-duplication and never reaches BACEN.

Example:

"b2696bf1-0a51-48b0-ab4a-8af2dff440af"

branch · string

Account branch (1..4 digits), optional.

Example:

"0001"

keyValue · string

PIX key value, formatted according to keyType: 11 digits for CPF, 14 alphanumeric characters for CNPJ, +55 plus an 11-digit mobile number for PHONE, an email address for EMAIL. REQUIRED for those four types and REFUSED for EVP — the chave aleatória is generated by the DICT, and the value it returns is the key.

Example:

"12345678901"

ownerTradeName · string

Owner trade name (legal-entity / CNPJ owners), optional.

Example:

"Silva ME"

ownerType · enum<string>

BACEN's Person discriminator for the key owner, sent verbatim on createEntry. Optional: omitted, it is resolved from ownerTaxId (11 characters natural, 14 legal). Supplied, it binds — a value contradicting ownerTaxId is refused, never honoured.

Available options: NATURAL_PERSON, LEGAL_PERSON

Example:

"NATURAL_PERSON"

possessionEvidence · object

Attestation that key possession was verified, as DICT 8.4 section 2.1 requires. Optional for CPF, CNPJ, EMAIL and PHONE keys; refused for EVP, where nothing is possessed. Omitting it does not refuse the registration — the absence is recorded in the key's audit trail. Supplied, it is validated in full and a malformed attestation is refused.

Show child attributes

Response

201

application/json

Created

Registered PIX key with its assigned status

createdAt · string · required

Key creation timestamp, RFC 3339 (UTC) — OUR row's local timestamp, not BACEN's; see creationDate for the DICT's own binding-creation instant.

Example:

"2025-03-07T14:30:00Z"

id · string · required

Unique PIX key identifier (UUID) assigned by the service.

Example:

"550e8400-e29b-41d4-a716-446655440000"

keyType · string · required

PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP (random key).

Example:

"CPF"

keyValue · string · required

PIX key value in its canonical format for the key type.

Example:

"12345678901"

ownerName · string · required

Full legal name of the key owner.

Example:

"João Silva"

ownerTaxId · string · required

Owner tax identifier: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (IN RFB 2.229/2024).

Example:

"12345678901"

participantISPB · string · required

Owning participant ISPB, the 8-digit BACEN institution identifier.

Example:

"12345678"

status · string · required

Key lifecycle status: ACTIVE, INACTIVE, PENDING_CLAIM, PENDING_BACEN_SYNC, or BLOCKED (judicial block, DICT 8.4 §1.1).

Example:

"ACTIVE"

updatedAt · string · required

Timestamp of the last update to the key, RFC 3339 (UTC).

Example:

"2025-03-07T14:30:00Z"

accountNumber · string

Account number (1..20 digits), omitted for a tuple-less key.

Example:

"9988776"

accountType · enum<string>

BACEN account type (CACC, SVGS, TRAN, SLRY, OTHR), omitted for a tuple-less key.

Available options: CACC, SVGS, TRAN, SLRY, OTHR

Example:

"CACC"

bacen · object

BACEN's own operational envelope for its most recent interaction on this key; omitted when no BACEN interaction has ever landed on it.

Show child attributes

branch · string

Account branch (1..4 digits), omitted when unset.

Example:

"0001"

creationDate · string<date-time>

BACEN's own creation instant for this key/account/owner binding, as the DICT answered it; omitted when BACEN's answer carried none.

Example:

"2020-01-15T00:00:00Z"

keyOwnershipDate · string<date-time>

Instant from which the owner has held uninterrupted possession of this key per BACEN; may differ from creationDate after a portability. Omitted when BACEN's answer carried none.

Example:

"2020-01-15T00:00:00Z"

openingDate · string<date-time>

Account opening date, RFC 3339, omitted for a tuple-less key.

Example:

"2020-01-15T00:00:00Z"

ownerTradeName · string

Owner trade name (legal-entity owners), omitted when unset.

Example:

"Silva ME"

ownerType · enum<string>

BACEN's own Person discriminator for the owner, as the DICT published it — not the value the registration declared, which is refused when the two could disagree. Omitted when BACEN's answer carried none.

Available options: NATURAL_PERSON, LEGAL_PERSON

Example:

"NATURAL_PERSON"

requestId · string<uuid>

The participant's own identifier for the registration that created this binding, echoed back. It is the value BACEN holds against the vinculo for life, so it is what a DICT support case and a retry are addressed by. Omitted for a key registered before this field existed or adopted by reconciliation — neither had a caller to state one.

Example:

"b2696bf1-0a51-48b0-ab4a-8af2dff440af"