Real-Time Lookup

Send the CPF (Brazil's individual taxpayer ID) and the date of birth and get the name, date of birth, year of death, registration status, control code and proof, straight from Receita Federal (Brazil's federal tax authority). It costs 1.5 credits per lookup.

Using Cursor, Lovable, v0 or another AI? Copy the Real-Time Lookup prompt and paste it into your assistant.

Open in Cursor

Using Cursor, Lovable, v0 or another AI? Copy the Real-Time Lookup prompt and paste it into your assistant.

Open in Cursor

Not the one you need? Compare the lookups.

Endpoint

POSThttps://api.cpfhub.io/cpf/realtime

Parameters

Where	Name	Required	Description
Header	`x-api-key`	Yes	Your API key, the same one used for the Simple Lookup. See Authentication.
Header	`Content-Type`	Yes	`application/json`
Body	`cpf`	Yes	CPF with or without formatting: `12345678909` or `123.456.789-09`
Body	`birthDate`	Yes	Date of birth, 8 digits (day, month, year): `DD/MM/YYYY` or `DDMMYYYY`. Separators are ignored. Year between 1900 and the current year.

Example

The examples read the key from CPFHUB_API_KEY, use a 60 s timeout and handle errors by HTTP status.

curl --max-time 60 -X POST "https://api.cpfhub.io/cpf/realtime" \
  -H "x-api-key: $CPFHUB_API_KEY" \
  -H "content-type: application/json" \
  -d '{
    "cpf": "12345678909",
    "birthDate": "15/06/1990"
  }'

Response

HTTP 200 OK

JSON

{
  "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?cp=12345678909&cc=ABCD1234EFGH5678&de=02102026&he=141516&dv=09&em=01",
    "validationHtmlUrl": "https://api.cpfhub.io/cpf/proof/12345678909/1790950516000"
  }
}

Field	Type	Description
`data.cpf`	`string`	CPF looked up, 11 digits without formatting
`data.name`	`string`	Name as recorded at Receita Federal, in uppercase
`data.birthDate`	`string`	Date of birth, `DD/MM/YYYY`
`data.deathYear`	`integer \| null`	Year of death. Always present: `null` when no death is recorded or when the received value is invalid. A valid value has 4 digits, falls between 1900 and the current year and cannot be earlier than the birth year.
`data.situation`	`string`	Registration status (table below)
`data.emissionDate`	`string`	Proof issue date, `DD/MM/YYYY`. Optional.
`data.emissionTime`	`string`	Issue time, `HH:MM:SS`. Optional.
`data.controlCode`	`string`	Proof control code (`XXXX.XXXX.XXXX.XXXX`). Optional.
`data.validationUrl`	`string`	Verification link on the Receita Federal website (the QR code destination). Optional.
`data.validationHtmlUrl`	`string`	Proof stored by CPFHub.io (HTML with a QR code). Optional.

Optional fields may be missing: they depend on what Receita Federal returns and on the proof generation. deathYear is not optional: the field is always present, with a valid integer or null.

Registration status

The situation values are returned in Portuguese, as recorded by Receita Federal.

`situation`	Meaning
`REGULAR`	CPF in good standing, no pending issues
`PENDENTE DE REGULARIZAÇÃO`	A tax return is missing or the registration needs updating (pending regularization)
`SUSPENSA`	Incorrect or incomplete registration (suspended)
`CANCELADA`	Registration closed by administrative or court decision, or because of multiple registrations (canceled)
`NULA`	Registration voided because of fraud (void)
`TITULAR FALECIDO`	Death recorded in the registry (deceased holder)

Only REGULAR indicates a CPF with no pending issues. Every status comes with 200 and uses credits.

Errors

The API only responds in Portuguese. Error messages are shown as returned, with the translation in parentheses the first time.

Status	When it happens	What to do
`400`	CPF without 11 digits, or `birthDate` missing or invalid	Fix the body. Do not retry.
`401`	Missing, invalid or inactive API key (`error` is a string)	Check the `x-api-key` header.
`403`	Not enough credits and no overage (`error.message`: `"Limite de créditos excedido"`, credit limit exceeded) or inactive/blocked account (`error` is a string)	Add credits or contact support. Do not retry.
`422`	Incorrect check digit, or Receita Federal refused the lookup (for example, date of birth mismatch)	Fix the CPF or the date. Does not use a credit. Handle it by status, not by text (the text comes from Receita Federal).
`429`	Per-minute limit exceeded (5/min by default)	Wait the seconds given in the `Retry-After` header. Does not use a credit.
`500`	Internal error	Report it if it persists.
`502`, `503`	Transient failure at Receita Federal or in the credit reservation	Retry with increasing wait times (2 s, 4 s, 8 s). Does not use a credit.

Error format, retries and how to test without spending credits: Error Codes. Per-minute limit and credits: Usage Limits.

Details

Cost: 1.5 credits per lookup that returns 200, for any registration status. Some plans have their own cost, so check your plan's cost in the dashboard.
Response time: about 1 second (typical, not an SLA). Use a timeout of at least 60 s. If your flow cannot wait, make the call asynchronously.
No batch: the lookup runs one CPF at a time.
Do not retry after a local timeout: the POST is not idempotent. The lookup may have completed and been charged. Check your balance with GET /quota before trying again.
Sample data: the CPF 12345678909 and the data above are fictional.

⚠

The proof link is public

Anyone with the validationHtmlUrl link can open the proof (name, CPF and status). Treat it as personal data: store it only on your back end, do not write it to logs and do not expose it on the front end.

Updated on October 4, 2026