Introduction

The CPFHub.io API lets you look up registration data linked to a CPF (Brazil's individual taxpayer ID): name, date of birth and gender, in a single authenticated HTTP request. It also queries the registration status directly at Receita Federal (Brazil's federal tax authority) and processes lists of CPFs in batch.

What you can do

Look up the full name, date of birth and gender by CPF number
Check whether a CPF has valid check digits
Calculate the holder's age from year, month and day
Add an age check to your signup or transaction flow
Query a CPF's registration status and year of death at Receita Federal in real time, with a control code and proof (Real-Time Lookup)

Endpoints

Method	Endpoint	Description	Cost
`GET`	`/cpf/{cpf}`	Simple Lookup: name, gender and date of birth from the CPFHub.io database	1 credit per CPF found
`POST`	`/cpf/realtime`	Real-Time Lookup at Receita Federal: registration status, year of death (`deathYear`, an integer or `null`), control code and proof	1.5 credits per successful lookup
`POST`	`/cpf/bulk`	Asynchronous batch lookup, up to 10,000 CPFs	1 credit per CPF found
`GET`	`/cpf/bulk/{jobId}`	Status and results of a batch	Free
`GET`	`/quota`	Credit balance, usage and plan	Free

The costs above are the defaults. Check the specific cost for your account in the dashboard.

Base URL

All requests must use HTTPS:

https://api.cpfhub.io

Requests over http:// get a 301 redirect to HTTPS. Many HTTP clients turn a POST into a GET when they follow that redirect, so always use https:// directly.

Response format

API responses use Content-Type: application/json. The exception is the proof (validationHtmlUrl), which is served as text/html.

Success (2xx):

JSON

{
  "success": true,
  "data": {
    "cpf": "12345678909",
    "name": "Fulano de Tal",
    "nameUpper": "FULANO DE TAL",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
  }
}

Error (4xx / 5xx):

JSON

{
  "success": false,
  "data": null,
  "error": {
    "message": "CPF não encontrado na base de dados"
  }
}

The API returns error messages in Portuguese only. This one means "CPF not found in the database". Use the HTTP status to decide the flow. Most errors carry error.message. Authentication and account errors (401 and 403 for a blocked account), 500 "Erro ao validar assinatura" ("error validating subscription") and 503 "usage_unavailable" carry error as a string:

JSON

{
  "success": false,
  "error": "API Key não fornecida"
}

Here the message means "API key not provided". To read the message in both formats: typeof body.error === 'string' ? body.error : body.error?.message. The full list is in Error Codes.

Authentication

Every request needs the x-api-key header with your API key:

bash

curl "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: YOUR_API_KEY"

Get your key for free at app.cpfhub.io/api-keys. The key is an opaque string, so do not depend on its prefix or format.

Next steps

Authentication: API keys and security
Simple Lookup: fields, parameters and examples
Real-Time Lookup: registration status, year of death and Receita Federal proof
Batch Lookup: up to 10,000 CPFs per request
Credit Balance: balance, usage and plan of your account
Usage Limits: credits per plan and the per-minute limit
Error Codes: the full list of errors and when to retry

Updated on October 3, 2026