---
title: "Consultar titular PIX quando a verificação estiver disponível"
method: GET
path: "/pix/keys/lookup"
tags: ["Pix"]
---

# Consultar titular PIX quando a verificação estiver disponível

`GET /pix/keys/lookup`

## Request

- Base URL: `https://api.luniumpay.com`
- URL: `https://api.luniumpay.com/pix/keys/lookup`
- Auth: API key in header `X-API-Key`

Consulta auxiliar de titular. Quando desabilitada, retorna HTTP 200 com verified=false, available=false, verification_status=not_performed, source=disabled e dados de titular nulos. Isso não desabilita pagamentos. Quando disponível, retorna dados obtidos do DICT sujeitos a cache e rate limit. Sandbox retorna titular fictício, source=sandbox. Não trate HTTP 200 isoladamente como titular verificado; envie type explícito quando souber o tipo.

## Query parameters

- `key` string, required
- `type` 'cpf' | 'cnpj' | 'phone' | 'email' | 'random'

## Response `200`

Titular encontrado.

- TitularPix
  - `pix_key` string, required: A chave, normalizada (telefone em +55…).
  - `pix_key_type` 'cpf' | 'cnpj' | 'phone' | 'email' | 'random', required: Tipo da chave consultada: "cpf", "cnpj", "phone", "email" ou "random".
  - `owner_name` string, nullable, required: Nome do titular, como está no DICT.
  - `owner_tax_number` string, nullable: CPF/CNPJ MASCARADO. Nunca vem inteiro.
  - `institution_name` string, nullable: Instituição onde a chave está registrada.
  - `ispb` string, nullable: ISPB da instituição (8 dígitos).
  - `verified` boolean, required: true quando titular foi consultado ou simulado (source=sandbox); false quando não verificado.
  - `source` 'dict' | 'sandbox' | 'disabled', required
  - `checked_at` string, date-time, required
  - `cached` boolean: true quando a resposta veio do cache de 24h.
  - `sandbox` boolean: Só em chave de teste: titular fictício.
  - `available` boolean: false quando consulta está indisponível; pode vir com HTTP 200.
  - `optional` boolean: Consulta é auxiliar; não é um requisito de pagamento.
  - `verification_status` string: not_performed quando a verificação não foi executada.
  - `detail` string

## Other responses

- `400`: Chave em formato inválido (`pix_key_invalida`) ou ausente (`pix_key_obrigatoria`).
- `401`: X-API-Key ausente, desconhecida ou incorreta.
- `404`: Chave não existe no DICT (`chave_nao_encontrada`).
- `429`: Limite de 5 consultas/min da conta (`limite_consultas`); leia `Retry-After`.
- `503`: Provedor DICT indisponível (`provedor_indisponivel`, repetir) ou consulta desligada (`consulta_indisponivel`, esperar).

---

[API](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil.md) · [All operations](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/llms.txt) · [OpenAPI document](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/revisions/0b5a340fa9dd?raw)