One call, one shape.

The whole integration is a single POST with CPF and name (IP optional). JSON responses, UTF-8, ISO 8601 dates.

Authentication

Send your key in the X-API-Key header (or Authorization: Bearer). Create and revoke keys in the dashboard. The full key is shown only once.

POST

/v1/lookup

Field	Type	Description
cpf required	string	With or without punctuation. Validated by its check digits.
name required	string	Full name. Compared with the CPF record and used to screen PEP and sanctions.
ip optional	string	End user’s IPv4 or IPv6. Enables the ip block and location signals.
birth_date optional	string	YYYY-MM-DD or DD/MM/YYYY. Returns whether it matches.
mother_name optional	string	Returns whether it matches.
purpose optional	string	Purpose of the lookup, written to the audit trail (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"
  }'

Response

The blocks never change. A block with no data is null; a provider failure does not fail the lookup — it shows up in sources.person.error.

cpf

valid, formatted, fiscal_region { code, ufs }

person

found, name_masked, sex, age_range, matches { name, birth_date, mother_name }, full (full mode only)

pep

is_pep, active, records [role, agency, start, end, grace period, match_confidence]

sanctions

is_sanctioned, active, records [list, type, agency, validity, match_confidence]

ip

country, uf, city, lat, lon, asn, org, is_hosting, is_private — null when not sent

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 }

Errors and billing

HTTP	error	Charged?
401	missing_api_key / invalid_api_key	No
422	invalid_cpf	No — failed the check digits
422	missing_name	No
422	invalid_ip	No
429	rate_limited / quota_exceeded	No
200	—	Yes, one lookup (even when answered from our database)

GET

/v1/usage

Lookups and provider calls per month for the last 12 months, plus the account’s quota and mode.