For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
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](https://docs.api.corpx.com/en/docs/guides/dict-lookups).**
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 twelve time ranges (`5m` through
`30d`): `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 (CPF, CNPJ, email, phone, or EVP).
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 DynamoDB cache.
Response
DICT lookup result.
cachedboolean
Whether the result was served from cache.
keystring
The PIX key value.
keyTypeenum
Type of the PIX key.
ownerNamestring
Account holder name.
ownerDocumentstring
Account holder document (CPF/CNPJ).
personTypeenum
Person type (individual or company).
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
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 twelve time ranges (5m through
30d): 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.
