Update PIX key

Updates a PIX key’s mutable bindings (account and owner name/trade name) and reports the change to BACEN DICT (signed updateEntry). keyType and ownerTaxId are immutable; an attempt to change them is rejected.

PUT /api/v1/dict/keys/{key}

Update PIX key

cURL

curl --request PUT \
  --url https://spi.sandbox.lerian.net/api/v1/dict/keys/{key} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "reason": "<string>",
  "accountNumber": "<string>",
  "accountType": "<string>",
  "branch": "<string>",
  "keyType": "<string>",
  "ownerName": "<string>",
  "ownerTaxId": "<string>",
  "ownerTradeName": "<string>",
  "participantISPB": "<string>"
}
'

200

{
  "createdAt": "<string>",
  "id": "<string>",
  "keyType": "<string>",
  "keyValue": "<string>",
  "ownerName": "<string>",
  "ownerTaxId": "<string>",
  "participantISPB": "<string>",
  "status": "<string>",
  "updatedAt": "<string>",
  "accountNumber": "<string>",
  "branch": "<string>",
  "openingDate": "2023-11-07T05:31:56Z",
  "ownerTradeName": "<string>"
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Path Parameters

key · string · required

PIX key value to update (the immutable identifier).

Body

application/json

Mutable key fields (account + owner name/trade name) and the update reason; keyType and ownerTaxId are immutable and rejected if changed.

reason · string · required

Update reason: USER_REQUESTED (not for EVP keys), BRANCH_TRANSFER, RECONCILIATION, or RFB_VALIDATION.

Example:

"BRANCH_TRANSFER"

accountNumber · string

New account number (account mutable field).

Example:

"9988776"

accountType · string

New account type (account mutable field).

Example:

"CACC"

branch · string

New account branch (account mutable field).

Example:

"0001"

keyType · string

Immutable: supplying a value differing from the stored keyType is rejected.

Example:

"CPF"

ownerName · string

New owner legal name (owner mutable field).

Example:

"João Silva"

ownerTaxId · string

Immutable: supplying a value differing from the stored ownerTaxId is rejected.

Example:

"12345678901"

ownerTradeName · string

New owner trade name (owner mutable field).

Example:

"Silva ME"

participantISPB · string

New owning participant ISPB (account mutable field).

Example:

"12345678"

Response

200

application/json

OK

Updated PIX key with its mutable fields applied

createdAt · string · required

Key creation timestamp, RFC 3339 (UTC).

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 (CPF or CNPJ), digits only.

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, or PENDING_BACEN_SYNC.

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, TRAN, SLRY, SVGS), omitted for a tuple-less key.

Available options: CACC, TRAN, SLRY, SVGS

Example:

"CACC"

branch · string

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

Example:

"0001"

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"