Real-Time Lookup
The CPF status,
straight from Receita Federal.
You provide the CPF (Brazil's individual taxpayer ID) and the date of birth. The lookup runs in real time at Receita Federal (Brazil's federal tax authority) and returns the registration status, the year of death, the issue date and time, and an HTML proof to file with the contract, the case or the audit.
1.5 credits per successful lookup. Same key, same plan, same balance.
What you get
Not just data. It is proof.
The difference between knowing and being able to demonstrate it later.
The CPF status
Regular, suspended, canceled, void, pending or deceased holder. Straight from Receita Federal's registry, not from an intermediate database.
The year of death
The deathYear field always comes back, as an integer or null. It is only the year, with no day or month. null appears when no death is on record or when the value received is invalid.
The HTML proof
A page with the lookup result, ready to file with a case, a contract or an audit, plus the link to validate it on the Receita Federal website.
Issue date and time
The exact moment Receita Federal responded. It is what shows the check was done before the decision.
The control code
The code that identifies the lookup at Receita Federal and lets you check the result on the Receita website.
Registration status
Six possible answers.
One of them clears the way. The other five are the reason you are looking it up.
Regular
CPF in good standing, no pending issues.
Pending regularization
A tax return is missing or the registration needs updating.
Suspended
Incorrect or incomplete registration.
Canceled
Closed by administrative or court decision, or because of duplication.
Void
Registration obtained through fraud.
Deceased holder
Death recorded in the Receita Federal registry.
Pricing
No separate package.
It comes out of the same balance.
At CPFHub.io, the Real-Time Lookup uses the same key, the same plan and the same credit balance as the Simple Lookup. Each successful lookup uses 1.5 credits by default (some plans have different values). You switch routes without switching contracts.
1.5 credits
per successful lookup, versus 1 credit for the Simple Lookup
0 credits
when Receita Federal is down or the date of birth does not match
50
free credits per month to try it out, no card required
Where to use it
When someone will ask for the proof.
Any flow where the decision becomes a contract, a payment or a record, and has to hold up later.
Hiring
Confirm the candidate's CPF before formalizing the hire. An irregular CPF blocks eSocial (Brazil's government payroll and labor reporting system) and creates rework for HR.
HR and HiringRentals
Tenant and guarantor verified before signing. A guarantee backed by an irregular CPF is a guarantee you cannot enforce.
Real EstateContracts and legal
The HTML proof documents the due diligence in identifying the parties, with date, time and control code.
Payroll and benefits
The response includes the year of death in deathYear and the status TITULAR FALECIDO (deceased holder) when the registry records a death. An improper payment is stopped before it goes out.
Insurance claims
Confirm the insured person with Receita Federal before releasing a payment, with an archivable record of what was checked.
InsuranceRegulated onboarding
When a regulator asks for proof of what you verified, the proof document is worth more than an API log.
How it works
Two data points go in. The proof comes out.
No digital certificate, no e-CNPJ (Brazilian company digital certificate), no electronic power of attorney, no queue on the Receita Federal website.
01
You send two data points
The CPF and the holder's date of birth. That is what Receita Federal requires to respond, so it is all we ask for.
02
We look it up on the spot
No intermediate database and no yesterday's copy. The lookup happens at Receita Federal, at the moment you call.
03
JSON and proof come back
Registration status, year of death (deathYear, integer or null), issue date and time, control code and the link to the HTML proof. Your system decides and files the proof.
The response depends on Receita Federal's response time. The typical time is about 1 second, not an SLA. If your flow cannot wait, the Simple Lookup covers the critical path and this one covers the proof.
Integrate in any language
The same key you already use, a different route. Ready-made examples in ten languages.
curl -X POST \
'https://api.cpfhub.io/cpf/realtime' \
-H 'x-api-key: YOUR_API_KEY' \
-H 'content-type: application/json' \
-d '{"cpf":"12345678909","birthDate":"15/06/1990"}'{
"success": true,
"data": {
"cpf": "12345678909",
"name": "FULANO DE TAL",
"birthDate": "15/06/1990",
"deathYear": null,
"situation": "REGULAR",
"emissionDate": "02/10/2026",
"emissionTime": "14:15:16",
"controlCode": "ABCD.1234.EFGH.5678",
"validationUrl": "https://servicos.receita.fazenda.gov.br/Servicos/CPF/ca/ResultadoAut.asp?...",
"validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/12345678909/1790950516000"
}
}FAQ
Frequently asked questions
What is the difference between the Simple Lookup and the Real-Time Lookup?
The Simple Lookup (GET /cpf/{cpf}) needs only the CPF, has a typical time of ~150 ms (not an SLA) from our database and returns name, gender and date of birth. The Real-Time Lookup (POST /cpf/realtime) takes the CPF and the date of birth in the JSON body, queries Receita Federal at the time of the call and returns registration status, year of death (deathYear, integer or null), control code and HTML proof, in about 1 second (typical time, not an SLA). They are independent routes: one never falls back to the other.
Why does the Real-Time Lookup require the date of birth?
Receita Federal itself requires it. The public lookup service only answers when it receives the CPF and the holder's date of birth together. If you do not have the date in your flow, the right route is the Simple Lookup.
Does the lookup return the year of death?
It returns the year of death in the deathYear field, always present, as an integer or null. It does not return day or month. null appears when no death is recorded or when the value received is invalid: it must have 4 digits, fall between 1900 and the current year and not be earlier than the birth year.
What does each registration status mean?
Regular: CPF in good standing. Pending regularization: a return is missing or the registration needs updating. Suspended: incorrect or incomplete registration. Canceled: closed by administrative or court decision, or because of a duplicate. Void: registration obtained by fraud. Deceased holder: death recorded in the registry.
How does the proof work?
The response includes validationHtmlUrl, an HTML proof with the lookup data, issue date and time and control code, and validationUrl, the link to check the lookup on the Receita Federal website. It is the record that supports a hire, a lease or a contract in an audit.
How much does the Real-Time Lookup cost?
By default, 1.5 credits per successful lookup, against 1 credit for the Simple Lookup (some plans have different values). It comes out of the same balance as your plan, with no separate package. Receita Federal down (502), unavailable (503) or a mismatched date of birth (422) do not debit credits.
How long does it take?
The Real-Time Lookup depends on Receita Federal's response time. The typical time is about 1 second, not an SLA. If your flow cannot wait, make the call asynchronously or use the Simple Lookup on the critical path.
Can I use the Real-Time Lookup in batch or through MCP?
Not in batch. POST /cpf/bulk covers only the Simple Lookup. Through the remote MCP server (https://api.cpfhub.io/mcp), yes: it exposes lookup_cpf (Simple Lookup), lookup_cpf_realtime (Real-Time Lookup, with CPF and date of birth, which also returns deathYear, the year of death, integer or null) and get_quota_info (balance). There is no batch tool in MCP. For volume on the Real-Time Lookup, talk to us on WhatsApp or at contato@cpfhub.io.
Do I need another account or another key?
No. It is the same account, the same x-api-key, the same plan and the same credit balance you already use on GET /cpf/{cpf}.
Still have questions?
Get in touchRegistration status
in real time.
Registration status, year of death, control code and HTML proof, straight from Receita Federal. 1.5 credits per lookup, from the same balance as your plan. 50 free credits to test.
Instant access to your API key and documentation.