Create a Pix key entry

Registers a new Pix key entry in the DICT directory. Assumes Receita Federal validation and MFA ownership authentication were completed by the client before the request. The account resolved from X-Account-Id must accept a new key binding: a salary account (SLRY) is refused with 422 PIX-0176 before any call to the DICT, while keys already bound to a salary account stay valid. After a 502 PIX-0141 or 500 PIX-0000 the outcome is unknown. Repeat the request with the same X-Idempotency and body, only within 30 minutes of the first attempt: the hub resends that attempt’s directory request. On the repeat, 201 is the original registration (for an EVP key the returned key is the first attempt’s only when the provider had completed that attempt, which the response does not show, so check the account’s entries before creating another EVP key). PIX-0102 confirms nothing: the first attempt may still be in progress, or the key is stored but not yet bound to the account (VSync reconciliation); look the key up and, while no entry for the account appears, repeat later with the same X-Idempotency within the window. A classified directory refusal (PIX-0103, PIX-0177, PIX-0178, PIX-0149, PIX-0100 or PIX-0179, below) means the first attempt was refused: fix the cause and use a new X-Idempotency. A repeated 502 PIX-0141 or 500 PIX-0000 is not a refusal: repeat again with the same X-Idempotency within the window, or look the key up. Past the 30 minutes, or under a different X-Idempotency, a repeat is a new directory request, which for an EVP key registers a new key: while the outcome is unknown, check the account’s entries instead of creating an EVP key again. An EVP create the hub cannot record for a later repeat is refused with 503 PIX-0032 before any call to the DICT, in a problem+json body (the replay gate’s own PIX-0032 uses the legacy envelope): repeat it after a few seconds. The DICT itself can still answer PIX-0102 (the provider already holds or is processing the key; for a key other than EVP repeated after a 502 PIX-0141 or 500 PIX-0000 past the window or under a different X-Idempotency, this usually means that attempt registered it and the entry appears after VSync reconciliation, otherwise look the key up or retry), PIX-0103 (400: its own key limit), PIX-0177 (409: the key belongs to a different person; an OWNERSHIP claim is the usual next step), PIX-0178 (409: the key belongs to the same owner at a different participant; a PORTABILITY claim is the usual next step), PIX-0149 (422: an open claim locks the key), PIX-0100 (422: a CPF/CNPJ key that is not the owner’s document) or PIX-0179 (422: a court-order or Pix restriction on the owner or account; do not show its message to end users). PIX-0141 (502) means the adapter call did not complete as a registration: an adapter or provider failure, which may have reached the DICT, or a provider refusal that has no classified code. None of these creates an entry.

POST /entries

Create a Pix key entry

cURL

curl --request POST \
  --url https://api.example.com/dict-hub/v1/entries \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --header 'X-Account-Id: <x-account-id>' \
  --header 'X-Idempotency: <x-idempotency>' \
  --header 'X-Reason: <x-reason>' \
  --data '
{
  "keyType": "CPF",
  "keyValue": "52998224725",
  "metadata": {
    "source": "mobile"
  }
}
'

201

Example

{
  "account": {
    "branch": "0001",
    "number": "0007654321",
    "participant": "12345678",
    "type": "CACC",
    "openingDate": "2010-01-10T03:00:00Z"
  },
  "createdAt": "2019-11-18T03:00:00Z",
  "id": "019606c3-5d6e-7f80-1b23-456789012cde",
  "keyCreationDate": "2019-11-18T03:00:00Z",
  "keyOwnershipDate": "2019-11-18T03:00:00Z",
  "keyType": "CPF",
  "keyValue": "52998224725",
  "organizationId": "019606d4-6e7f-8091-2c34-567890123def",
  "owner": {
    "document": "52998224725",
    "name": "João Silva",
    "personType": "NATURAL",
    "tradeName": "Silva ME"
  },
  "requestId": "a946d533-7f22-42a5-9a9b-e87cd55c0f4d",
  "status": "ACTIVE",
  "updatedAt": "2019-11-18T03:00:00Z",
  "holderId": "019606e5-7f80-9102-3d45-678901234ef0",
  "metadata": {}
}

Authorizations

Authorization · string · header · required

JWT bearer token issued by the identity provider.

Headers

X-Idempotency · string · required

REQUIRED. Client-supplied replay key, at most 64 bytes. A request without it is refused with PIX-0030 @ 400 before the handler runs. Replaying the same key with a divergent method, URL or body is PIX-0031 @ 412.

Required string length: 1 - 64

X-Account-Id · string · required

Account ID (UUID format)

Example:

"019606a1-3b4c-7d8e-9f01-234567890abc"

X-Reason · string · required

Reason for creating the entry: USER_REQUESTED or RECONCILIATION

Example:

"USER_REQUESTED"

Body

application/json

keyType · string · required

Pix key type

Example:

"CPF"

keyValue · string

Pix key value

Example:

"52998224725"

metadata · object

Free-form, single-level key/value pairs persisted with the entry. Keys up to 100 characters, values up to 2000 characters, at most 25 entries; nested objects are rejected.

Show child attributes

Example:

{ "source": "mobile" }

Response

201

application/json

Created

account · object · required

Show child attributes

createdAt · string<date-time> · required

Example:

"2019-11-18T03:00:00Z"

id · string · required

Example:

"019606c3-5d6e-7f80-1b23-456789012cde"

keyCreationDate · string<date-time> · required

Example:

"2019-11-18T03:00:00Z"

keyOwnershipDate · string<date-time> · required

Example:

"2019-11-18T03:00:00Z"

keyType · string · required

Example:

"CPF"

keyValue · string · required

Example:

"52998224725"

organizationId · string · required

Example:

"019606d4-6e7f-8091-2c34-567890123def"

owner · object · required

Show child attributes

requestId · string · required

Example:

"a946d533-7f22-42a5-9a9b-e87cd55c0f4d"

status · string · required

Example:

"ACTIVE"

updatedAt · string<date-time> · required

Example:

"2019-11-18T03:00:00Z"

holderId · string

CRM holder of the key's account. Absent while a key VSync synchronized from the directory waits for its owner's CRM account.

Example:

"019606e5-7f80-9102-3d45-678901234ef0"

metadata · object

Show child attributes