Identity lookup

Overview

Look up official Brazilian registry data by taxpayer identification number:

Both endpoints are GET: the signed body is the empty string and all path variables (CNPJ / CPF / date of birth) are part of the signed path, see Authentication. Responses are bare objects (no platform envelope); business errors are a bare {code, message} object.

Why CPF requires a date of birth

The upstream source validates CPF and date of birth as a pair (Receita Federal semantics); a CPF alone returns nothing. A mismatched pair and a non-existent CPF return the same error code: they are deliberately not distinguished, otherwise the endpoint would become a tool for probing other people's birth dates.

Onboarding

1. Application credential: apply for an application and receive an app_secret. It is displayed only once; store it securely.
2. API subscription: the platform grants your application access to the endpoints you need (the scope key is the endpoint path).

Endpoints

Error model

Two error shapes

Business, request-level and upstream errors (HTTP 400 / 422 / 428 / 451 / 503) are returned as a bare object:

{ "code": 10016003, "message": "CPF not found" }

Authentication-layer errors (HTTP 401 / 403 / 429) are produced by the platform gateway before the request reaches the API, and use the platform envelope:

{ "success": false, "errorType": 1, "code": 10009005, "message": "API not subscribed, please subscribe before calling" }

Note: your error handler must accept both shapes. A robust rule: parse the body as JSON, read code from either shape, and treat success=false or HTTP >= 400 as failure.

Business error codes

Format and check-digit errors are rejected locally by the platform and never reach the upstream source: they consume no quota and are not billed.

Responsibility convention: 10016000 to 10016003 and 10016010 to 10016012 are caller-side problems; 10016004 to 10016006 are lawful third-party blocks; 10016020 is a third-party outage; HTTP 500 + 10001000 is a platform fault.

Billing: 10016003 (not found / birth date mismatch), 10016004 (under 16) and 10016005 (age 16 to 17) are billed per call; 10016006 (age unverifiable), 10016020 (upstream outage) and locally rejected format / check-digit errors are not billed. The age tiers are described in detail on the CPF lookup page.

Authentication and authorization errors

Retry guidance: 401 and 403 are configuration errors; retrying without a fix is pointless and may trip rate limits. 429 and 503 (10016020) are retryable with backoff. 422 / 428 / 451 are statutory blocks; retrying is pointless. For 500, contact the platform with the failing request's timestamp and path.

HTTP status quick reference

Data protection

CPF is personal data of a natural person and is governed by Brazil's LGPD (Law 13.709/2018):

• The platform does not persist CPF lookup results; every query hits the source in real time.
• Full CPF values never enter application logs; they are masked.
• Path variables in the call log are HMAC-processed before storage; no plaintext is retained.
• The upstream source lawfully withholds data for minors; the platform passes the 451 / 422 / 428 status through unchanged and stores nothing. 451 / 422 are billed per call, 428 is not; see Minors and age verification on the CPF lookup page.

Callers are expected to observe the same minimum-necessity principle: query only where there is a lawful business basis (such as invoice issuance), and do not retain personal data beyond what the business requires.

Response localization

The message field follows the request language: the Language header (en / pt / es / zh) takes precedence, then Accept-Language (supports pt-BR and q-values). Without a language header, responses default to Portuguese (pt).

For programmatic decisions always use the numeric code and enum values such as situacao.codigo; never match on description text. The message of the LGPD blocking tiers is the statutory Portuguese wording and is not translated.

Integration checklist

1. Obtain the app_secret and confirm both endpoints are subscribed.
2. Call with a real CNPJ: HTTP 200, ni echoes the input, situacaoCadastral.codigo is 2.
3. Call with a real CPF + date of birth: HTTP 200, nascimento echoes the input.
4. Negative case: correct CPF with a wrong date of birth returns 400 + 10016003 (same code as not-found).
5. Negative case: CNPJ / CPF with bad check digits returns 400 + 10016011 / 10016001 (rejected locally, not billed).
6. Negative case: date of birth as 1997-01-09 or 31021997 returns 400 + 10016002.
7. Failure paths: call with a wrong sign (401 + 10009003); call an unsubscribed endpoint (403 + 10009005).
8. Parser compatibility: make sure your client treats 422 / 428 / 451 / 503 as failures and reads the bare {code, message} body (these cannot be triggered with test data; they only appear in production for real minors' CPFs).

Troubleshooting

1. A GET request did not concatenate the body as the empty string "" (an empty object or placeholder text was used instead);
2. path missing the /openapi prefix, or including the query string;
3. The date-of-birth segment left out of the CPF signature; both path variables must be signed;
4. sign sent in uppercase (must be lowercase hex);
5. The timestamp used in concatenation differs from the header (regenerated between the two);
6. A formatted CNPJ whose / split the path.

Recompute the fixed values of the signing example in Authentication first; once your local implementation matches, move on to inspecting the live request parameters.