curl --request POST \
  --url https://api.example.com/v1/entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "keyType": 2,
  "isValidated": false,
  "ispb": "12345678",
  "key": "foo@bar.com"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"keyType\": 2,\n  \"isValidated\": false,\n  \"ispb\": \"12345678\",\n  \"key\": \"foo@bar.com\"\n}")

	req, _ := http.NewRequest("POST", 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: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    keyType: 2,
    isValidated: false,
    ispb: '12345678',
    key: 'foo@bar.com'
  })
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "keyType": 2,
    "isValidated": False,
    "ispb": "12345678",
    "key": "foo@bar.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "key": "11122233300",
  "keyType": 4,
  "status": 1,
  "statusDescription": "ACTIVE"
}

{
  "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"
  }
}

Register a PIX key entry

Registers a PIX key for the account named by accountId, and is also the only entry point to the claim flow. keyType must agree with the value in key (0=CPF, 1=CNPJ, 2=EMAIL, 3=PHONE, 4=RANDOM) or the call is 422 PIX-0010 naming the expected and detected types; omit key for RANDOM and DICT mints the EVP value (§8.2.01). isValidated is accepted but ignored - the service always restarts validation.

An unvalidated EMAIL or PHONE key never reaches DICT on this call: the service stores it locally as awaiting ownership confirmation (status 2), sends a 6-digit code to that address, and answers with status 2. Finish it with POST /v1/entries//confirmation. Calling this route again for the same key re-arms the row with a NEW code and the previous one stops working. A key of those two types that the account already holds at DICT is 409 PIX-0071. CPF, CNPJ and RANDOM keys go straight to DICT.

If DICT answers that the key is already registered elsewhere, the call still SUCCEEDS: the service records a claim-pending row (status 4) carrying the claim type DICT implied - portability when the current holder’s document matches yours, possession otherwise (§8.2.07) - and no claim is opened yet. Opening it is POST /v1/claims, which works only on a row this call created. The whole operation is idempotent on (accountId, key): an existing live row is returned with its current status rather than registered a second time.

The service records the registration as pending (status 8) BEFORE it asks DICT. If DICT does not answer in time the call is 504 PIX-1051, and if DICT cannot be reached it is 503 PIX-1054 - never 500 - and the pending record stays: DICT may still have registered the key. Retrying the same CPF, CNPJ, EMAIL or PHONE key re-sends the same request, which DICT deduplicates. For RANDOM, whose value only DICT knows, the next RANDOM request for the account first reads the account’s DICT keys: when DICT lists exactly ONE EVP that this deployment never recorded, it is adopted and returned as ACTIVE instead of minting another; when it lists none, or several unrecorded EVPs (there is then no telling which one was this account’s), a new RANDOM request is 409 PIX-0007 for up to 10 minutes after the unanswered one, after which the pending record is released and a new EVP is registered.

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. A key written under the wrong participant is declared to Bacen by the wrong institution, and there is no undo.

POST

entries

curl --request POST \
  --url https://api.example.com/v1/entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "keyType": 2,
  "isValidated": false,
  "ispb": "12345678",
  "key": "foo@bar.com"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"keyType\": 2,\n  \"isValidated\": false,\n  \"ispb\": \"12345678\",\n  \"key\": \"foo@bar.com\"\n}")

	req, _ := http.NewRequest("POST", 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: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    accountId: 'acc-123',
    keyType: 2,
    isValidated: false,
    ispb: '12345678',
    key: 'foo@bar.com'
  })
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "keyType": 2,
    "isValidated": False,
    "ispb": "12345678",
    "key": "foo@bar.com"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "key": "11122233300",
  "keyType": 4,
  "status": 1,
  "statusDescription": "ACTIVE"
}

{
  "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.

Body

application/json

accountId

string

required

The CRM account id of the key owner.

Example:

"acc-123"

keyType

integer<int64>

required

Numeric eKeyType (0=CPF,1=CNPJ,2=EMAIL,3=PHONE,4=RANDOM).

Example:

2

isValidated

boolean

Ignored: the service always forces validation to start fresh.

Example:

false

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"

key

string

The PIX key value (omit for a RANDOM key).

Example:

"foo@bar.com"

Response

Created

key

string

The PIX key value.

Example:

"11122233300"

keyType

integer<int64>

Numeric eKeyType.

Example:

4

status

integer<int64>

Numeric eKeyStatus.

Example:

1

statusDescription

string

Human-readable eKeyStatus label.

Example:

"ACTIVE"

Direct participant APIs

Indirect participant APIs

Register a PIX key entry

Authorizations

Body

Response