Change a PIX key entry

curl --request PUT \
  --url https://api.example.com/v1/entries/{entryId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "reason": 2,
  "accountOpeningDate": "2020-01-10T11:30:17.001Z",
  "ispb": "12345678",
  "newAccount": "0007654321",
  "newAccountType": 0,
  "newBranch": "0001",
  "newName": "Empresa Nova",
  "newTradeName": "Fantasia Nova"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/entries/{entryId}"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"reason\": 2,\n  \"accountOpeningDate\": \"2020-01-10T11:30:17.001Z\",\n  \"ispb\": \"12345678\",\n  \"newAccount\": \"0007654321\",\n  \"newAccountType\": 0,\n  \"newBranch\": \"0001\",\n  \"newName\": \"Empresa Nova\",\n  \"newTradeName\": \"Fantasia Nova\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    reason: 2,
    accountOpeningDate: '2020-01-10T11:30:17.001Z',
    ispb: '12345678',
    newAccount: '0007654321',
    newAccountType: 0,
    newBranch: '0001',
    newName: 'Empresa Nova',
    newTradeName: 'Fantasia Nova'
  })
};

fetch('https://api.example.com/v1/entries/{entryId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/entries/{entryId}"

payload = {
    "accountId": "acc-123",
    "reason": 2,
    "accountOpeningDate": "2020-01-10T11:30:17.001Z",
    "ispb": "12345678",
    "newAccount": "0007654321",
    "newAccountType": 0,
    "newBranch": "0001",
    "newName": "Empresa Nova",
    "newTradeName": "Fantasia Nova"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

{
  "key": "foo@bar.com",
  "claimOpenedAt": "2026-01-03T00:00:00Z",
  "createdAt": "2026-01-01T00:00:00Z",
  "ownershipStartAt": "2026-01-02T00:00:00Z"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Change a PIX key entry

Re-points an existing PIX key to a new transactional account and/or a new owner name inside the SAME participant (§8.2.02 Alterar Chave de Endereçamento). entryId is the key VALUE, URL-encoded, and it never changes - no operation in this API edits a key’s value.

Only the destination travels in the body: newBranch, newAccountType, newAccount, accountOpeningDate, newName and newTradeName, all optional per the spec. The owner identity (ISPB, CPF/CNPJ, person type) is derived server-side from accountId and is never read from the payload. reason is required and is DICT’s reason code: 0=Customer Request, 2=Branch Transfer, 6=Reconciliation, 8=Receita Federal Validation; an EVP (RANDOM) key must not use 0.

When the change moves the key to another account (newAccount or newAccountType differs from accountId’s own), the plugin clears the account link on the holder’s local rows of the key, so every account of the holder lists it until it is deleted; a change that keeps the key on its account leaves the rows alone. DICT may open a possession or portability claim as a consequence of the change; when it does, the response carries claimOpenedAt. Failures are DICT’s, translated into the PIX-1xxx family - an unknown key is 404 PIX-1011.

Which of this deployment’s direct participants writes to the national directory is decided by ispb, by exactly the rule an order’s payerIspb follows: this deployment may act as several direct participants, each with its own ISPB and its own DICT credential, and naming none is answerable only while there is one answer. Omit it while this deployment acts as a single participant; once it acts as several, omitting it is 422 PIX-0127 and naming one it is not is 422 PIX-0128. When the account named on the request cannot be used by that participant, the request is refused before the operation acts and the answer names the account: 422 PIX-0137 when it is held in a ledger that is not configured for Pix, 422 PIX-0138 when its record does not say which ledger holds it, and 422 PIX-0139 when its record names a different institution. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.

PUT

entries

{entryId}

Change a PIX key entry

curl --request PUT \
  --url https://api.example.com/v1/entries/{entryId} \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "reason": 2,
  "accountOpeningDate": "2020-01-10T11:30:17.001Z",
  "ispb": "12345678",
  "newAccount": "0007654321",
  "newAccountType": 0,
  "newBranch": "0001",
  "newName": "Empresa Nova",
  "newTradeName": "Fantasia Nova"
}
'

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/v1/entries/{entryId}"

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"reason\": 2,\n  \"accountOpeningDate\": \"2020-01-10T11:30:17.001Z\",\n  \"ispb\": \"12345678\",\n  \"newAccount\": \"0007654321\",\n  \"newAccountType\": 0,\n  \"newBranch\": \"0001\",\n  \"newName\": \"Empresa Nova\",\n  \"newTradeName\": \"Fantasia Nova\"\n}")

	req, _ := http.NewRequest("PUT", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

const options = {
  method: 'PUT',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    reason: 2,
    accountOpeningDate: '2020-01-10T11:30:17.001Z',
    ispb: '12345678',
    newAccount: '0007654321',
    newAccountType: 0,
    newBranch: '0001',
    newName: 'Empresa Nova',
    newTradeName: 'Fantasia Nova'
  })
};

fetch('https://api.example.com/v1/entries/{entryId}', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.example.com/v1/entries/{entryId}"

payload = {
    "accountId": "acc-123",
    "reason": 2,
    "accountOpeningDate": "2020-01-10T11:30:17.001Z",
    "ispb": "12345678",
    "newAccount": "0007654321",
    "newAccountType": 0,
    "newBranch": "0001",
    "newName": "Empresa Nova",
    "newTradeName": "Fantasia Nova"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.put(url, json=payload, headers=headers)

print(response.text)

{
  "key": "foo@bar.com",
  "claimOpenedAt": "2026-01-03T00:00:00Z",
  "createdAt": "2026-01-01T00:00:00Z",
  "ownershipStartAt": "2026-01-02T00:00:00Z"
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

{
  "code": "<string>",
  "detail": "Property foo is required but is missing.",
  "errors": [
    {
      "location": "<string>",
      "message": "<string>",
      "value": "<unknown>"
    }
  ],
  "instance": "https://example.com/error-log/abc123",
  "status": 400,
  "title": "Bad Request",
  "type": "https://example.com/errors/example",
  "upstream": {
    "code": "E4001",
    "message": "account not found at provider"
  }
}

Authorizations

Authorization

string

header

required

JWT bearer token issued by the identity provider.

Path Parameters

entryId

string

required

The PIX key value (URL-encoded).

Example:

"foo@bar.com"

Body

application/json

accountId

string

required

The CRM account id of the key owner (resolves the server-side ISPB).

Example:

"acc-123"

reason

integer<int64>

required

Change reason (0=Customer Request,2=Branch Transfer,6=Reconciliation,8=Receita Federal Validation). EVP keys must not use 0.

Example:

2

accountOpeningDate

string

The new account's opening timestamp (RFC3339).

Example:

"2020-01-10T11:30:17.001Z"

ispb

string

The ISPB of the direct participant this operation acts as. This deployment may act as SEVERAL direct SPI participants - one ISPB each, each with its own customers and its own DICT credential - and this field is the only thing on the request that says which of them writes to the national directory. OPTIONAL while it acts as a single participant: omit it and that one acts. REQUIRED once it acts as several - omitted is 422 PIX-0127, and an ISPB this deployment does not act as is 422 PIX-0128. It is ROUTING DATA you supply and guarantee, exactly like payerIspb on a transaction: never a credential, never read from a header or a path, and it never widens what your token can reach. It also selects the DICT credential the call goes out on, so a key registered under the wrong one is declared to Bacen by the wrong institution. Send it as an absent key, not an empty string; an empty value is refused 400 PIX-0061.

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

Example:

"12345678"

newAccount

string

The new account number to associate with the key.

Example:

"0007654321"

newAccountType

integer<int64>

The new account type (0=Checking,1=Salary,2=Savings,3=Payment,4=PI).

Example:

0

newBranch

string

The new branch number to associate with the key.

Example:

"0001"

newName

string

The new owner full name / legal name.

Example:

"Empresa Nova"

newTradeName

string

The new owner trade name (sent only for a corporate owner).

Example:

"Fantasia Nova"

Response

key

string

required

The PIX key (unchanged).

Example:

"foo@bar.com"

claimOpenedAt

string

When a possession/portability claim was opened by the change (RFC3339), if any.

Example:

"2026-01-03T00:00:00Z"

createdAt

string

When the key was created (RFC3339).

Example:

"2026-01-01T00:00:00Z"

ownershipStartAt

string

When ownership of the key began (RFC3339).

Example:

"2026-01-02T00:00:00Z"

Direct participant APIs

Indirect participant APIs

Change a PIX key entry

Authorizations

Path Parameters

Body

Response