CPF Lookup API

The Simple Lookup takes only the CPF (Brazil's individual taxpayer ID) and returns name, gender and date of birth. Typical response time is ~150 ms (not an SLA) and the cost is 1 credit per CPF found. The Real-Time Lookup takes the CPF and the date of birth, queries Receita Federal (Brazil's federal tax authority) when the request is made and returns the registration status, the year of death (deathYear, an integer or null) and the proof. Typical response time is about 1 second (not an SLA) and the cost is 1.5 credits, charged only on an HTTP 200 response. The Batch Lookup processes up to 10,000 CPFs per upload, with the same data as the Simple Lookup. Batch time depends on how many CPFs are in the upload, and each lookup falls in the same range as the Simple Lookup. All three use the same API key and the same credit balance.

No. You can look up CPFs directly in the dashboard, one at a time or by uploading a .csv or .txt file with up to 10,000 CPFs. The API is for those who want to automate lookups in their own system.

The Simple Lookup and the Batch Lookup answer from the CPFHub.io database. The Real-Time Lookup queries Receita Federal when the request is made and returns the registration status, the year of death and the proof issued by Receita Federal.

Yes, through the Real-Time Lookup. It reports whether the CPF is regular, suspended, pending regularization, canceled or void, or whether the holder is recorded as deceased. It also returns the year of death in the deathYear field (an integer or null) and the date and time the proof was issued. deathYear is null when no death is on record or when the value received is invalid. It does not include the day or month of death. To run the lookup, you must send the holder's date of birth. The Simple Lookup does not return the registration status or the year of death.

In the Real-Time Lookup, yes: the deathYear field holds the year of death, always present, as an integer or null. It does not include the day or month. null appears when no death is on record or when the value received is invalid (it does not have 4 digits, falls outside the range between 1900 and the current year, or is earlier than the birth year). The Simple Lookup and the Batch Lookup do not return this field.

The Simple Lookup has a typical response time of ~150 ms. The Real-Time Lookup has a typical response time of about 1 second, because it queries Receita Federal when the request is made. These are typical figures, not an SLA. In the Batch Lookup, time depends on how many CPFs are in the upload, and each lookup falls in the same range as the Simple Lookup. Availability has an SLA per plan: 95% on Free, 99% on PRO and 99.9% on Enterprise.

Yes. Each lookup is logged (CPF, result, date and account) for history, billing, audit and fraud prevention, with a retention period defined in the Privacy Policy. Your company, as the data controller, must define the legal basis and the legitimate purpose of each lookup.

Yes. When you create a free account, with no credit card, you get 50 credits per month. The API key is available in the dashboard right away.

In the Simple Lookup and the Batch Lookup, a credit is used only when the CPF is found, at 1 credit per CPF. A CPF that is not found is not charged. In the Real-Time Lookup, the cost is 1.5 credits, charged only on an HTTP 200 response. A mismatched date of birth returns HTTP 422 and is not charged.

Billing is monthly. The Free plan gives you 50 credits at no cost. The PRO plan starts at R$ 19 per month (Brazilian reais, BRL), with 100 credits, and has tiers of up to 10,000 credits. Overage credits cost from R$ 0.19 to R$ 0.10, depending on the tier, and are billed on next month's invoice. The Enterprise plan has custom pricing.

No. The only limit is the plan's credit balance: as long as you have balance, you can call the API at whatever pace you need. On the Free plan, lookups are paused when the 50 monthly credits run out. On paid plans, the API keeps responding after the limit, and the overage is billed on next month's invoice.