Verify PIX key existence

curl --request POST \
  --url https://api.example.com/v1/entries/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "keys": [
    "foo@bar.com",
    "11122233300"
  ],
  "ispb": "12345678"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"keys\": [\n    \"foo@bar.com\",\n    \"11122233300\"\n  ],\n  \"ispb\": \"12345678\"\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', keys: ['foo@bar.com', '11122233300'], ispb: '12345678'})
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "keys": ["foo@bar.com", "11122233300"],
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "keys": [
    {
      "exists": true,
      "key": "foo@bar.com"
    }
  ],
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "jdpiReturnedAt": "2021-04-08T10:30:05.025Z"
}

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

Verify PIX key existence

Bulk-checks whether each supplied PIX key exists in the DICT directory (§8.2.23 Verificar Existência de Chaves). accountId resolves the caller’s ISPB only - it does not scope the answer - and keys carries 1 to 200 values; a batch outside those bounds is refused before any DICT call, with 400 PIX-0061 naming keys.

What comes back is existence and nothing else: each row is a key plus an exists flag. It does not say who holds a key, whether YOU hold it, or whether it can be claimed, so it is not the pre-check for a claim - POST /v1/entries is, because that is what turns a key DICT already knows into the claim-pending row POST /v1/claims requires. Use this to sift a list of keys, for example before a batch payout. The response also echoes DICT’s own jdpiReturnedAt and correlationId, which are the values support asks for.

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.

POST

entries

verification

Verify PIX key existence

curl --request POST \
  --url https://api.example.com/v1/entries/verification \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "accountId": "acc-123",
  "keys": [
    "foo@bar.com",
    "11122233300"
  ],
  "ispb": "12345678"
}
'

package main

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

func main() {

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

	payload := strings.NewReader("{\n  \"accountId\": \"acc-123\",\n  \"keys\": [\n    \"foo@bar.com\",\n    \"11122233300\"\n  ],\n  \"ispb\": \"12345678\"\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', keys: ['foo@bar.com', '11122233300'], ispb: '12345678'})
};

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

import requests

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

payload = {
    "accountId": "acc-123",
    "keys": ["foo@bar.com", "11122233300"],
    "ispb": "12345678"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.text)

{
  "keys": [
    {
      "exists": true,
      "key": "foo@bar.com"
    }
  ],
  "correlationId": "a9f13566e19f5ca51329479a5bae60c5",
  "jdpiReturnedAt": "2021-04-08T10:30:05.025Z"
}

{
  "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 caller (resolves the server-side ISPB).

Example:

"acc-123"

keys

string[]

required

The PIX keys whose DICT existence to check (1..200).

Required array length: 1 - 200 elements

Example:

["foo@bar.com", "11122233300"]

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"

Response

keys

object[] | null

required

The per-key existence results.

Show child attributes

correlationId

string

DICT support correlation id.

Example:

"a9f13566e19f5ca51329479a5bae60c5"

jdpiReturnedAt

string

When DICT returned the verification (RFC3339).

Example:

"2021-04-08T10:30:05.025Z"

Direct participant APIs

Indirect participant APIs

Verify PIX key existence

Authorizations

Body

Response