Skip to navigation

DICT key lookup

Looks up a PIX key in the DICT (Diretório de Identificadores de Contas Transacionais).

Before integrating this endpoint, read the PIX key lookups guide. DICT is a rationed resource metered by BACEN per institution. Every lookup is recorded and measured in real time, per account, across twelve time windows, and the consumption is watched continuously by CorpX. Abuse — key scanning, or using DICT as a source of registry data — leads to a warning, tighter limits, account suspension and, if it persists, termination of access. The same guide explains what acceptable usage looks like and how to follow your own consumption in the Integrator Portal.

Results are cached for 24 hours. Cache hits return cached: true and do not count toward DICT rate limits. Send noCache=true to force a fresh lookup.

Rate limits are configurable per tenant or account via the dictLookup policy:

  • maxLookupsPerDay — absolute cap per calendar day (BRT). Unset inherits the global default; a negative value means unlimited.
  • maxLookupsPerMinute and maxNotFoundPer5min — burst caps, same convention.
  • windows — rate caps over fourteen time ranges (5m through 90d): maxUsageRatio is lookups per completed transfer in the window, maxFailureRatio is the fraction of lookups resolving no key, and minLookups is the sample floor below which neither rule can refuse. A range with no values declared inherits the fleet baseline, so rate management is always on.

Every limit is counted per account, never summed across the tenant. A limit configured on a tenant policy is a template applied to each of its accounts individually.

The most restrictive applies. Exceeding any of them returns 429 dict_lookup_limit_exceeded with the offending counter or window in message.

Only lookups that reached DICT count toward these caps. Partner failures and requests already refused with 429 are not charged to the quota. Resolving a key inside a PIX Out by key counts the same as an explicit lookup; a 24h cache hit does not count.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path parameters

accountIdstringRequired
Account identifier.
pixKeystringRequired

PIX key to look up, in the format DICT stores it, percent-encoded as a URL path segment (encodeURIComponent in JavaScript, urllib.parse.quote(key, safe="") in Python):

  • CPF: 11 digits, no punctuation — 12345678909
  • CNPJ: 14 digits, no punctuation — 11222333000181
  • Phone: +55, area code and number (E.164) — +5511999998888, sent as %2B5511999998888
  • Email: the address — fulano@exemplo.com, sent as fulano%40exemplo.com
  • Random key (EVP): UUID with hyphens — 123e4567-e89b-12d3-a456-426614174000

A phone without +55 (11999998888) is read as a CPF and returns 400 invalid_pix_key, as does a masked phone. The / in a masked CNPJ splits the path even when encoded as %2F and returns a route 404. On the Internet banking host, sign the path exactly as sent, with the key encoded.

Headers

X-Tenant-IdstringRequired
Tenant context used for authorization and routing.
X-Request-TimestampstringRequired

Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).

X-Content-SHA256stringRequired

Lowercase hex SHA-256 of the body. An empty body hashes the empty string, so the header is always present. Mismatch returns 400 body_hash_mismatch.

X-Request-SignaturestringRequired

Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.

Query parameters

keyTypeenumOptional

Key type. Auto-inferred from format if not provided.

Allowed values:
noCachebooleanOptionalDefaults to false

When true, bypasses the 24h lookup cache.

Response

DICT lookup result.
cachedboolean
Whether the result was served from cache.
keystring
The PIX key value.
keyTypeenum
Type of the PIX key.
Allowed values:
ownerNamestring
Account holder name.
ownerDocumentstring

Account holder document (CPF/CNPJ).

personTypeenum

Person type (individual or company).

Allowed values:
bankNamestring
Bank name.
bankCodestring

Bank code (COMPE).

bankIspbstring
Bank ISPB code.
branchstring
Branch number.
accountNumberstring
Account number.
accountTypestring

Account type (e.g., CHECKING_ACCOUNT).

statusstring

Key status (e.g., ACTIVE).

createdAtdatetime
When the key was registered.
cachedAtdatetimeOptional

When the result was cached (present when cached=true).

Errors

404
Not Found Error
422
Unprocessable Entity Error
429
Too Many Requests Error
500
Internal Server Error
502
Bad Gateway Error
503
Service Unavailable Error
504
Gateway Timeout Error