> This page is for BaaS.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://en.docs.api.corpx.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://en.docs.api.corpx.com/_mcp/server.

# PIX key lookups (DICT)

DICT — *Diretório de Identificadores de Contas Transacionais* — is the BACEN
registry that says who owns a PIX key. Every time you ask "whose key is this",
CorpX asks DICT on your behalf.

That question is a rationed resource. BACEN meters DICT consumption **per
institution**, and CorpX answers for everything its integrators look up. A client
scanning keys in bulk does not only spend their own allowance: they degrade DICT
access for everyone operating with us, and expose the institution to regulatory
sanction.

That is why lookup consumption is measured in real time, account by account, and
watched continuously by CorpX. This page describes what we measure, what you can
see, what we expect of your traffic, and what happens when that expectation is
broken.

> **Read this before integrating key lookups**
>
> DICT abuse is not treated as a technical nuisance to be tolerated. It leads to a
> warning, tighter limits on your account, account suspension and, if it persists,
> termination of your access to the institution. See
> [Warning, suspension and termination](#warning-suspension-and-termination).

## Every lookup is recorded

Each trip to DICT becomes a permanent record on our side, with the account that
asked, where the question came from, the timestamp and the outcome — key found,
key not found, key refused by DICT, or technical failure. None of this is
sampled: it is the complete log, and it feeds both the numbers you see in the
portal and the ones we see.

There are two ways to look a key up, and both count:

* **The explicit lookup** — `GET /v1/accounts/{accountId}/pix/key/{pixKey}`.
* **PIX Out in `KEY` mode** — `POST /v1/accounts/{accountId}/pix/out`, `/async`
  and `/bigpix`. The key must be resolved before the money leaves, and that
  question goes to the same DICT.

## How to put the key in the URL

The key goes in the path. Send it in the format DICT stores it and **encoded as
a URL path segment** (percent-encoding): `@` becomes `%40` and `+` becomes
`%2B`. Encode only the key, with your language's URL-component function —
`encodeURIComponent(key)` in JavaScript, `urllib.parse.quote(key, safe="")` in
Python —, never the whole path, which would turn its slashes into `%2F`.

| Type         | Format                              | Key                                    | In the path                                        |
| ------------ | ----------------------------------- | -------------------------------------- | -------------------------------------------------- |
| CPF          | 11 digits, no punctuation           | `12345678909`                          | `.../pix/key/12345678909`                          |
| CNPJ         | 14 digits, no punctuation           | `11222333000181`                       | `.../pix/key/11222333000181`                       |
| Phone        | `+55`, area code and number (E.164) | `+5511999998888`                       | `.../pix/key/%2B5511999998888`                     |
| Email        | the address                         | `fulano@exemplo.com`                   | `.../pix/key/fulano%40exemplo.com`                 |
| Random (EVP) | UUID with hyphens                   | `123e4567-e89b-12d3-a456-426614174000` | `.../pix/key/123e4567-e89b-12d3-a456-426614174000` |

```bash
curl "https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/key/fulano%40exemplo.com" \
  -H "Authorization: Bearer {token}" \
  -H "X-Tenant-Id: tenant-yourcompany"
```

What does not work:

* **Phone without `+55`.** `11999998888` has 11 digits and is read as a CPF,
  not a phone: the lookup returns `400 invalid_pix_key`. Phones always carry the
  country code.
* **Masks.** A masked phone — `(11) 99999-8888` — returns `400 invalid_pix_key`.
  In a CNPJ, the `/` of `11.222.333/0001-81` splits the path even when encoded
  as `%2F`, and the response is a `404` for a route that does not exist. Strip
  the punctuation before the lookup.

A malformed key is a wasted lookup and counts toward your failure rate: validate
the format before asking DICT.

## What is measured

Two kinds of rule run over that record, evaluated on every lookup. The most
restrictive one wins.

### Absolute counts: how much and how fast

| Limit                 | Window             | What it prevents                                                                  |
| --------------------- | ------------------ | --------------------------------------------------------------------------------- |
| `maxLookupsPerDay`    | calendar day (BRT) | Total volume beyond what was agreed                                               |
| `maxLookupsPerMinute` | rolling 60s        | Bursts: fits the daily cap, but arrives all at once                               |
| `maxNotFoundPer5min`  | rolling 5 min      | Enumeration: blind scanning produces many `NOT_FOUND` before the daily cap closes |

### Rates: what use you make of the lookups

Count limits cannot tell apart someone looking up to pay from someone looking up
to collect. An account can sit comfortably within 500 lookups a day and still
spend 40 lookups per PIX — the profile of someone scanning keys, not paying. Two
rates separate the cases:

| Rate                                      | What it measures                                                                                          | What it reveals                     |
| ----------------------------------------- | --------------------------------------------------------------------------------------------------------- | ----------------------------------- |
| **Lookups per payment** (`maxUsageRatio`) | lookups ÷ completed PIX by key in the window. A PIX by key paid without a prior lookup counts as a lookup | Lookups that never become payments  |
| **Failure rate** (`maxFailureRatio`)      | (keys not found + refused) ÷ lookups in the window                                                        | Scanning for keys that do not exist |

Both are computed over **fourteen simultaneous time windows** — `5m`, `15m`, `30m`,
`1h`, `3h`, `6h`, `12h`, `24h`, `3d`, `7d`, `14d`, `30d`, `60d` and `90d`. The short window
catches the burst; the long one catches patient abuse, the kind that hides
diluted across a day. Spreading a scan over a week does not help: the 7-day
window sees the whole week.

Every window has a **sample floor** (`minLookups`). Below it neither rate can
refuse, because a rate computed over three calls means nothing. That is what
lets a new account make its first lookups in peace.

**A window with no declared numbers is not a window turned off.** It inherits the
fleet baseline, and rate management is always on. The values in force, the
configuration convention and the defaults are in
[Policies and Rules](/baas/guias/autenticacao/politicas#dict-lookup-limits).

### Everything is measured per account

No limit is aggregated per tenant. One account's lookups never count against
another, even within the same tenant — including when the limit was configured at
tenant level, which works as a template applied to each account individually. The
account is the unit because that is where the burst happens and where the
penalty lands.

### What does not consume quota

* **Cache hits.** Repeat lookups of the same key are served from a 24h cache, and
  a cache hit costs nothing. The cache is shared between both paths: an explicit
  lookup serves the payment that follows, and vice versa.
* **Technical failures, ours or the settlement provider's.** Downtime is not your
  fault and does not burn quota.
* **A lookup already refused with `429`.** Someone already blocked does not dig
  deeper with every retry.

## You see exactly what we see

In the [Integrator Portal](https://backoffice.api.corpx.com), the **PIX lookup
bucket** screen shows the same numbers that feed the decision to refuse. There is
no hidden measurement: if the portal says you are at 60% of the cap, that is what
the limit engine is reading.

For the selected window, the screen shows:

* **Lookups, completed PIX Outs, lookups that resolved no key, and lookups
  refused by a limit** — tenant totals and the same breakdown per account.
* **Lookups per payment and failure rate**, each with the measured value, a bar
  for how much of the cap is spent, and the cap in force.
* **Each account's state** in the window: within the limit, close to it, or over.
* **All fourteen windows side by side** when you open an account, which is where
  you can tell a one-off burst from a sustained pattern.
* **The list of refused lookups** from the last 30 days, one row per `429`.

Watching this screen is how you correct course before being blocked — and, if
your legitimate use case does not fit the current rule, it is the material you
use to request a review of your policy.

## When a limit closes

The lookup is refused with `429` and `errorCode: dict_lookup_limit_exceeded`. The
message says which rule closed, what was measured and what the cap was:

```
DICT lookup usage too high for this account in the last 1h:
120 lookups for 10 successful transfers (12.0 per transfer); max 6.0
```

```
DICT lookup failure rate too high for this account in the last 5m:
18 of 24 lookups did not resolve a key (75%); max 40%
```

When more than one window is over, the response cites **the shortest one** — it
is the immediate cause and the first to clear.

Every refusal also fires the `policy.violation` webhook with
`phase: "dict_lookup"`, so you can react without waiting for someone to look at
the screen.

### How to get out of a block

The windows slide: they clear on their own as time passes and the excess falls
out of the measured range. A 5-minute window clears in minutes; a 30-day one does
not.

What does **not** work is insisting. A refused lookup is not charged, but it does
not speed up the release either, and a burst of retries against an already-closed
limit is exactly the pattern that leads to the escalation below. Treat `429` as a
stop signal: halt the traffic, find on the screen which window closed, and wait
for it to open.

If the refusal comes from a long window and your volume is legitimate, talk to
support instead of trying to work around it.

> **Not every \`429\` is your quota**
>
> The same route returns `429` with `errorCode: partner_rate_limited` when the
> settlement provider throttles CorpX's traffic. That is not your limit and no
> counter of yours closed. Check the `errorCode` before concluding your quota ran
> out.

## What we expect of your traffic

There is no trick to it: whoever uses DICT to pay stays far from the limits. The
rule was calibrated against real traffic from integrators in production and
blocked none of them.

**Do:**

* Look up the key you are about to pay, at the moment you are about to pay it.
* Use the 24h cache. Re-displaying a recipient you already looked up needs no new
  trip to DICT, and `?noCache=true` is only justified when ownership may have
  changed.
* Validate the key format before asking. A malformed key is a wasted lookup and
  raises your failure rate.
* Treat `429` as a stop, with backoff, and monitor the `policy.violation` webhook.
* Watch the bucket screen and ask for a policy review **before** hitting the cap,
  when growth is expected.

**Do not:**

* Scan ranges of tax IDs, phone numbers or emails to discover which keys exist.
  That is the behaviour the `NOT_FOUND` limits exist to catch, and the one CorpX
  treats with the least tolerance.
* Look up keys to enrich a database, validate a customer base, confirm ownership
  outside a payment, or feed a lookup product of your own. DICT is not a source
  of registry data, and that use is barred by PIX regulation, not just by our
  policy.
* Spread the same scan across several accounts of your tenant to dilute the
  measurement. Each account is measured on its own, but the pattern across the
  tenant is visible to us and is judged as a single behaviour.
* Retry against a limit that has already closed.

## Warning, suspension and termination

CorpX reviews DICT consumption across the whole fleet continuously, with a
cross-tenant, cross-account view. When a pattern of abuse shows up, the response
is proportional and escalates:

1. **Contact and warning.** We reach out through the support channel with the
   numbers behind the observation and a deadline to correct it.
2. **Tighter limits.** Your policy gets caps stricter than the baseline, on the
   offending account or on the whole tenant. You keep operating, with less room.
3. **Account suspension.** The account is suspended by a manual, audited action
   from a CorpX operator, with the reason on record. **While it lasts, every
   route of that account returns `403 forbidden`** — not just key lookups. The
   tenant's other accounts keep operating.
4. **Tenant suspension or shutdown.** If it persists, or if the case is severe
   enough, the tenant's access is suspended — `403 tenant_suspended`, with write
   operations blocked and reads still available — or disabled entirely, with
   `403 tenant_disabled`.

These steps are not a mandatory script. Deliberate key scanning, using DICT as a
source of registry data, and attempts to work around the measurement skip the
early steps, because they expose the institution immediately.

Reactivation is never automatic: it goes through support, depends on the cause
having been fixed, and is recorded along with the operator who authorised it.

> **A description of conduct, not a replacement for your contract**
>
> This page describes how the control works in practice and what the operation
> does. The commercial terms and regulatory obligations in your contract with CorpX
> remain fully in force and prevail in case of divergence.

## Where to read more

* [Policies and Rules](/baas/guias/autenticacao/politicas#dict-lookup-limits) — the field reference,
  defaults, precedence between account and tenant, and how to configure them.
* [Errors](/baas/guias/referencia/erros) — the full catalogue, including
  `dict_lookup_limit_exceeded` and `partner_rate_limited`.
* [Webhooks](/baas/guias/conta/webhooks) — delivery, retries and signing of
  `policy.violation`.
* Questions about your use case: the support channel or `api@corpx.com`. Asking
  before you integrate costs less than fixing it after being blocked.