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](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.

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