Uma chamada, um formato.

A integração inteira é um POST com CPF e nome (IP opcional). Respostas em JSON, UTF-8, datas em ISO 8601.

Autenticação

Envie sua chave no cabeçalho X-API-Key (ou Authorization: Bearer). Crie e revogue chaves no painel. A chave completa aparece uma única vez.

POST

/v1/lookup

Campo	Tipo	Descrição
cpf obrigatório	string	Com ou sem máscara. Validado pelos dígitos verificadores.
name obrigatório	string	Nome completo. Comparado ao cadastro e usado para cruzar PEP e sanções.
ip opcional	string	IPv4 ou IPv6 do usuário final. Ativa o bloco ip e os sinais de localização.
birth_date opcional	string	AAAA-MM-DD ou DD/MM/AAAA. Retorna se confere.
mother_name opcional	string	Retorna se confere.
purpose opcional	string	Finalidade da consulta, gravada na trilha de auditoria (LGPD).

curl -X POST https://api.quecpf.com/v1/lookup \
  -H "X-API-Key: $QUECPF_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cpf": "529.982.247-25",
    "name": "Maria da Silva",
    "ip": "200.147.3.10",
    "purpose": "onboarding"
  }'

Resposta

Os blocos são sempre os mesmos. Um bloco sem dado vem null; uma falha do fornecedor não derruba a consulta — aparece em sources.person.error.

cpf

valid, formatted, fiscal_region { code, ufs }

person

found, name_masked, sex, age_range, matches { name, birth_date, mother_name }, full (só modo completo)

pep

is_pep, active, records [cargo, órgão, início, fim, carência, match_confidence]

sanctions

is_sanctioned, active, records [lista, tipo, órgão, vigência, match_confidence]

ip

country, uf, city, lat, lon, asn, org, is_hosting, is_private — null se não enviado

signals

person_found, name_match, pep_active, sanction_active, ip_country_br, ip_uf_matches_cpf_region, ip_is_hosting

sources

person { provider, cached, fetched_at, error }, datasets { pep, ceis, cnep, ceaf }

Erros e cobrança

HTTP	error	Cobra?
401	missing_api_key / invalid_api_key	Não
422	invalid_cpf	Não — falhou nos dígitos verificadores
422	missing_name	Não
422	invalid_ip	Não
429	rate_limited / quota_exceeded	Não
200	—	Sim, uma consulta (mesmo vinda da base própria)

GET

/v1/usage

Consultas e chamadas a fornecedor por mês, últimos 12 meses, mais cota e modo da conta.