Simple Lookup

Send the CPF (Brazil's individual taxpayer ID) and get the name, gender and date of birth from the CPFHub.io database. It costs 1 credit per CPF found.

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

Open in Cursor

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

Open in Cursor

Not the one you need? Compare the lookups.

Endpoint

GEThttps://api.cpfhub.io/cpf/{cpf}

Parameters

Where	Name	Required	Description
Path	`cpf`	Yes	CPF with or without formatting: `12345678909` or `123.456.789-09`
Header	`x-api-key`	Yes	Your API key. See Authentication.

Example

The examples read the key from CPFHUB_API_KEY, treat 404 as a normal result and use a 10 s timeout. Other languages: Examples by language.

curl --max-time 10 "https://api.cpfhub.io/cpf/12345678909" \
  -H "x-api-key: $CPFHUB_API_KEY"

Response

HTTP 200 OK

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
  }
}

Field	Type	Description
`data.cpf`	`string`	CPF looked up, 11 digits without formatting
`data.name`	`string`	Full name. It may come in uppercase, so use `nameUpper` when comparing
`data.nameUpper`	`string`	Full name in uppercase
`data.gender`	`"M"` \| `"F"` \| `null`	Gender. `null` when the database has no information
`data.birthDate`	`string`	Date of birth, `DD/MM/YYYY`
`data.day`, `data.month`, `data.year`	`number`	Components of the date of birth

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	Fix the CPF. Do not retry.
`401`	Missing, invalid or inactive API key (`error` is a string)	Check the `x-api-key` header.
`403`	No credits left 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.
`404`	CPF not found in the database	Normal result. Does not use a credit.
`422`	Incorrect check digit	Fix the CPF. Do not retry.
`429`	Per-minute limit exceeded (30/min by default)	Wait the seconds given in the `Retry-After` header. Does not use a credit.
`500`, `503`	Transient failure	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 credit per CPF found (200). Some plans have their own cost, so check your plan's cost in the dashboard.
Response time: typical ~150 ms (not an SLA). Use a timeout of about 10 s.
Client timeout: the lookup may have completed and been charged on the server. Retrying charges again.
Sample data: the CPF 12345678909 and the data above are fictional.

Updated on October 4, 2026