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.maxLookupsPerMinuteandmaxNotFoundPer5min— burst caps, same convention.windows— rate caps over fourteen time ranges (5mthrough90d):maxUsageRatiois lookups per completed transfer in the window,maxFailureRatiois the fraction of lookups resolving no key, andminLookupsis 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
Bearer authentication of the form Bearer <token>, where token is your auth token.
Path parameters
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 asfulano%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
Unix seconds. Required on the signed host; tolerance is 300s either way (403 request_timestamp_skew).
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.
Detached JWS (<protected>..<signature>, ES256 or PS256) over METHOD\nPATH?QUERY\nTIMESTAMP\nIDEMPOTENCY_KEY_OR_EMPTY\nX_CONTENT_SHA256.
Query parameters
Key type. Auto-inferred from format if not provided.
When true, bypasses the 24h lookup cache.
Response
Account holder document (CPF/CNPJ).
Person type (individual or company).
Bank code (COMPE).
Account type (e.g., CHECKING_ACCOUNT).
Key status (e.g., ACTIVE).
When the result was cached (present when cached=true).