Lookup PIX key

Looks up a PIX key by JSON body value. This deployment’s own key registry is read FIRST — a retained BACEN answer can never outrank a local row (DICT 8.4 §1.1) — and only a key with no local row falls through to the retained BACEN answer and then to BACEN DICT. Returns ownerTaxId full and unmasked per BACEN API-DICT. A judicially blocked key answers EntryBlocked with HTTP 400 and none of the key’s data, identically to a BACEN-relayed block.

POST /api/v1/dict/keys/lookup

Lookup PIX key

cURL

curl --request POST \
  --url https://spi.sandbox.lerian.net/api/v1/dict/keys/lookup \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "endToEndId": "E1234567820260220123456789012350",
  "keyValue": "12345678901",
  "payerId": "12345678901",
  "includeStatistics": false,
  "requestingParticipant": "12345678"
}
'

200

{
  "createdAt": "2025-03-07T14:30:00Z",
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "keyType": "CPF",
  "keyValue": "12345678901",
  "ownerName": "João Silva",
  "ownerTaxId": "12345678901",
  "participantISPB": "12345678",
  "status": "ACTIVE",
  "updatedAt": "2025-03-07T14:30:00Z",
  "accountNumber": "9988776",
  "accountType": "CACC",
  "bacen": {
    "correlationId": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
    "lastModified": "2026-06-14T12:00:00Z",
    "responseTime": "2026-06-14T12:00:00Z"
  },
  "branch": "0001",
  "creationDate": "2020-01-15T00:00:00Z",
  "keyOwnershipDate": "2020-01-15T00:00:00Z",
  "keyStatistics": {
    "entries": {
      "watermark": "2023-01-01T10:00:00.000Z",
      "distinctAccounts": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "registeredAccounts": "0"
    },
    "fraudMarkers": {
      "applicationFrauds": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "distinctFraudReporters": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "muleAccounts": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "otherFrauds": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "scammerAccounts": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "totalFraudTransactionAmount": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "unknownFrauds": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "infractionReports": {
      "openReports": "0",
      "openReportsDistinctReporters": "0",
      "rejectedReports": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "spi": {
      "settlements": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    }
  },
  "openClaimCreationDate": "2026-08-01T00:00:00Z",
  "openingDate": "2020-01-15T00:00:00Z",
  "ownerStatistics": {
    "entries": {
      "watermark": "2023-01-01T10:00:00.000Z",
      "distinctAccounts": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "registeredAccounts": "0"
    },
    "fraudMarkers": {
      "applicationFrauds": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "distinctFraudReporters": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "muleAccounts": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "otherFrauds": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "scammerAccounts": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "totalFraudTransactionAmount": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "unknownFrauds": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "infractionReports": {
      "openReports": "0",
      "openReportsDistinctReporters": "0",
      "rejectedReports": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    },
    "spi": {
      "settlements": {
        "d90": "0",
        "m12": "0",
        "m60": "0"
      },
      "watermark": "2023-01-01T10:00:00.000Z"
    }
  },
  "ownerTradeName": "Silva ME",
  "ownerType": "NATURAL_PERSON"
}

Autorizaciones

Authorization · string · header · requerido

JWT bearer token issued by the identity provider.

Cuerpo

application/json

PIX key value to resolve — against this deployment's own key registry first, then a retained BACEN answer, then BACEN DICT

endToEndId · string · requerido

EndToEndId the pacs.008 this query feeds will carry (E{ISPB}{YYYYMMDD}{HHMM}{uniqueID}, 32 characters). Shaped exactly as the pacs.008 XSD types EndToEndIdType — the participant segment admits [0-9A-Z] and the unique tail is case-sensitive and may be lower-case — so this surface never refuses an id the wire it feeds accepts. Required: it is BACEN's own rate-limiting key for the query, and the id under which the ficha this query spends is credited back once the payment order is sent.

Pattern: ^E[0-9A-Z]{8}[0-9]{12}[a-zA-Z0-9]{11}$

Ejemplo:

"E1234567820260220123456789012350"

keyValue · string · requerido

PIX key value to look up, in its canonical format for the key type. At most 77 characters, the ceiling BACEN publishes on a DICT key.

Required string length: 1 - 77

Ejemplo:

"12345678901"

payerId · string · requerido

CPF (11 digits) or CNPJ (14 digits) of the end user originating this query — the payer of the payment order it feeds. Required: BACEN bills the query to this user's own request-limiting bucket, and every query by the same end user must carry the same identifier. Digits only.

Pattern: ^([0-9]{11}|[0-9]{14})$

Ejemplo:

"12345678901"

includeStatistics · boolean

Opt into BACEN antifraud statistics blocks (ownerStatistics/keyStatistics) inline on the answer. Default false — trades one fewer round-trip on the payment path for a heavier response; has no effect when the key resolves from this deployment's own records, and forces a fresh directory query for a key that does not.

Ejemplo:

false

requestingParticipant · string

Who is asking, when it is not this deployment: an indirect participant's own ISPB (DICT 8.4 R079). Must be a participant this deployment is authorized to query for — its own direct, or an active indirect it sponsors; any other value is rejected, because BACEN bills the query and its antiscan debit to whoever this names. Omit and this deployment's own ISPB is sent.

Pattern: ^[A-Za-z0-9]{8}$

Ejemplo:

"12345678"

Respuesta

200

application/json

OK

Resolved PIX key details, including ownerTaxId full and unmasked per BACEN API-DICT

createdAt · string · requerido

Key creation timestamp, RFC 3339 (UTC) — OUR row's local timestamp, not BACEN's; see creationDate for BACEN's own binding-creation instant.

Ejemplo:

"2025-03-07T14:30:00Z"

id · string · requerido

Unique PIX key identifier (UUID) assigned by the service.

Ejemplo:

"550e8400-e29b-41d4-a716-446655440000"

keyType · string · requerido

PIX key type: CPF, CNPJ, EMAIL, PHONE, or EVP (random key).

Ejemplo:

"CPF"

keyValue · string · requerido

PIX key value in its canonical format for the key type.

Ejemplo:

"12345678901"

ownerName · string · requerido

Full legal name of the key owner.

Ejemplo:

"João Silva"

ownerTaxId · string · requerido

Owner tax identifier: 11 digits for a CPF, 14 alphanumeric characters for a CNPJ (IN RFB 2.229/2024); returned full and unmasked per BACEN API-DICT.

Ejemplo:

"12345678901"

participantISPB · string · requerido

Owning participant ISPB, the 8-digit BACEN institution identifier.

Ejemplo:

"12345678"

status · string · requerido

Key lifecycle status: ACTIVE, INACTIVE, PENDING_CLAIM, or PENDING_BACEN_SYNC. A judicially blocked key (DICT 8.4 §1.1) never reaches this response: the lookup answers EntryBlocked with HTTP 400 and no key data.

Ejemplo:

"ACTIVE"

updatedAt · string · requerido

Timestamp of the last update to the key, RFC 3339 (UTC).

Ejemplo:

"2025-03-07T14:30:00Z"

accountNumber · string

Account number (1..20 digits), omitted for a tuple-less key.

Ejemplo:

"9988776"

accountType · enum<string>

BACEN account type (CACC, SVGS, TRAN, SLRY, OTHR), omitted for a tuple-less key.

Opciones disponibles: CACC, SVGS, TRAN, SLRY, OTHR

Ejemplo:

"CACC"

bacen · object

BACEN's own operational envelope for its most recent interaction on this key. A foreign key resolved live off BACEN carries the envelope of that very call. Omitted only when no BACEN interaction has ever landed on this key.

Show child attributes

branch · string

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

Ejemplo:

"0001"

creationDate · string<date-time>

BACEN's own creation instant for this key/account/owner binding: decoded from this lookup's answer for a foreign key, or stamped from createEntry's answer for a key this deployment registered. Omitted when BACEN never published one.

Ejemplo:

"2020-01-15T00:00:00Z"

keyOwnershipDate · string<date-time>

Instant from which the owner has held uninterrupted possession of this key per BACEN; may differ from creationDate after a portability. Same availability as creationDate.

Ejemplo:

"2020-01-15T00:00:00Z"

keyStatistics · object

Key-scoped BACEN antifraud statistics (verbatim), present only when the request opted in via includeStatistics and the lookup resolved live off BACEN DICT.

Show child attributes

openClaimCreationDate · string<date-time>

When the key's current open ownership/portability claim started, per BACEN; omitted when no claim is open at answer time or the lookup did not resolve live off BACEN DICT.

Ejemplo:

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

openingDate · string<date-time>

Account opening date, RFC 3339, omitted for a tuple-less key.

Ejemplo:

"2020-01-15T00:00:00Z"

ownerStatistics · object

Owner-scoped BACEN antifraud statistics (verbatim), present only when the request opted in via includeStatistics and the lookup resolved live off BACEN DICT.

Show child attributes

ownerTradeName · string

Owner trade name (legal-entity owners), omitted when unset.

Ejemplo:

"Silva ME"

ownerType · enum<string>

BACEN's own Person discriminator for the owner, as the DICT published it — never the value a registration declared. Same availability as creationDate.

Opciones disponibles: NATURAL_PERSON, LEGAL_PERSON

Ejemplo:

"NATURAL_PERSON"