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

# DICT key lookup

GET https://tenant.api.corpx.com/v1/accounts/{accountId}/pix/key/{pixKey}

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


Reference: https://en.docs.api.corpx.com/baas/referencia/pix/dict-key-lookup

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `accountId` (string, required) — Account identifier.
- `pixKey` (string, required) — 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.

### Query parameters

- `keyType` (enum, optional) — Key type. Auto-inferred from format if not provided.
  - Allowed values: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
- `noCache` (boolean, optional, default: false) — When `true`, bypasses the 24h lookup cache.

### Headers

- `X-Tenant-Id` (string, required) — Tenant context used for authorization and routing.

## Response

### 200

DICT lookup result.

- `cached` (boolean, required) — Whether the result was served from cache.
- `key` (string, required) — The PIX key value.
- `keyType` (enum, required) — Type of the PIX key.
  - Allowed values: `CPF`, `CNPJ`, `EMAIL`, `PHONE`, `EVP`
- `ownerName` (string, required) — Account holder name.
- `ownerDocument` (string, required) — Account holder document (CPF/CNPJ).
- `personType` (enum, required) — Person type (individual or company).
  - Allowed values: `PF`, `PJ`
- `bankName` (string, required) — Bank name.
- `bankCode` (string, required) — Bank code (COMPE).
- `bankIspb` (string, required) — Bank ISPB code.
- `branch` (string, required) — Branch number.
- `accountNumber` (string, required) — Account number.
- `accountType` (string, required) — Account type (e.g., CHECKING_ACCOUNT).
- `status` (string, required) — Key status (e.g., ACTIVE).
- `createdAt` (datetime, required) — When the key was registered.
- `cachedAt` (datetime, optional) — When the result was cached (present when cached=true).

## Errors

### 404 Not Found Error

Requested resource was not found.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 422 Unprocessable Entity Error

Business validation error returned by banking partner.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 429 Too Many Requests Error

Rate limit exceeded. Two different limits produce this status: - `dict_lookup_limit_exceeded` — your account's own DICT quota. The `message` says which counter or time window triggered and the current usage. - `partner_rate_limited` — the banking provider throttled CorpX's traffic. Nothing is wrong with your request; retry with backoff.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 500 Internal Server Error

Unexpected server error.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 502 Bad Gateway Error

Failure on the CorpX↔provider leg (`partner_error`, `partner_unauthorized`, `partner_unavailable`, `partner_internal`). Not caused by your credential.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 503 Service Unavailable Error

Partner temporarily unavailable.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

### 504 Gateway Timeout Error

Timeout while contacting banking partner.

- `errorCode` (string, required) — Stable machine-readable code. See `ErrorCode` for the known values.
- `message` (string, required) — Human-readable explanation (pt-BR). Presentation only; may change.
- `docs` (string, optional) — Link to this code in the public error catalogue.
- `requestId` (string, optional) — Gateway request id. Quote it when contacting support.
- `details` (map from string to any, optional) — Optional machine-readable context for the specific `errorCode` (for example `kind` on `identity_verification_monthly_limit_exceeded`, `maxBytes` on `payload_too_large`, `attemptsRemaining` on `facetec_attempts_exhausted`). Keys are documented per operation; absent when the code carries no extra context.
- `partner` (ErrorResponsePartner, optional) — Raw error from the settlement bank, when the failure came from it. Diagnostic only.

## Types

### ErrorResponsePartner

Raw error from the settlement bank, when the failure came from it. Diagnostic only.

- `code` (string, optional)
- `message` (string, optional)
- `field` (string, optional) — Field the partner pointed at, when any.

## Examples

**Response**

```json
{
  "cached": true,
  "key": "12345678900",
  "keyType": "CPF",
  "ownerName": "MARIA DA SILVA",
  "ownerDocument": "12345678900",
  "personType": "PF",
  "bankName": "Banco BTG Pactual S.A.",
  "bankCode": "36741675",
  "bankIspb": "36741675",
  "branch": "0001",
  "accountNumber": "200037834",
  "accountType": "PIX",
  "status": "COMPLETED",
  "createdAt": "2026-02-20T08:33:39Z",
  "cachedAt": "2026-02-20T08:33:39Z"
}
```

**SDK Code**

```python Pix_dictKeyLookup_example
import requests

url = "https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888"

headers = {
    "X-Tenant-Id": "X-Tenant-Id",
    "Authorization": "Bearer <token>"
}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript Pix_dictKeyLookup_example
const url = 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888';
const options = {
  method: 'GET',
  headers: {'X-Tenant-Id': 'X-Tenant-Id', Authorization: 'Bearer <token>'}
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Pix_dictKeyLookup_example
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("X-Tenant-Id", "X-Tenant-Id")
	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Pix_dictKeyLookup_example
require 'uri'
require 'net/http'

url = URI("https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["X-Tenant-Id"] = 'X-Tenant-Id'
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Pix_dictKeyLookup_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888")
  .header("X-Tenant-Id", "X-Tenant-Id")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Pix_dictKeyLookup_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'X-Tenant-Id' => 'X-Tenant-Id',
  ],
]);

echo $response->getBody();
```

```csharp Pix_dictKeyLookup_example
using RestSharp;

var client = new RestClient("https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888");
var request = new RestRequest(Method.GET);
request.AddHeader("X-Tenant-Id", "X-Tenant-Id");
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Pix_dictKeyLookup_example
import Foundation

let headers = [
  "X-Tenant-Id": "X-Tenant-Id",
  "Authorization": "Bearer <token>"
]

let request = NSMutableURLRequest(url: NSURL(string: "https://tenant.api.corpx.com/v1/accounts/accountId/pix/key/%2B5511999998888")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```