GET /cpf - Consulta de CPF

Retorna nome, gênero e data de nascimento a partir de um número de CPF brasileiro.

Endpoint

bash

GET https://api.cpfhub.io/cpf/{cpf}

Autenticação

Envie sua API Key no header x-api-key. Veja Autenticação.

Parâmetros

Path

Parâmetro	Tipo	Obrigatório	Descrição
`cpf`	`string`	Sim	CPF com ou sem formatação. Aceita `12345678909` ou `123.456.789-09`.

Headers

Header	Obrigatório	Descrição
`x-api-key`	Sim	Sua API Key do CPFHub.io
`Content-Type`	Não	Não é necessário para GET

Exemplos de requisição

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

Resposta de sucesso

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

Campos da resposta

Campo	Tipo	Descrição
`success`	`boolean`	`true` se a consulta foi bem-sucedida
`data.cpf`	`string`	CPF consultado (somente dígitos)
`data.name`	`string`	Nome completo em capitalização normal
`data.nameUpper`	`string`	Nome completo em maiúsculas
`data.gender`	`"M"` \| `"F"`	Gênero - `M` masculino, `F` feminino
`data.birthDate`	`string`	Data de nascimento no formato `DD/MM/AAAA`
`data.day`	`number`	Dia de nascimento
`data.month`	`number`	Mês de nascimento
`data.year`	`number`	Ano de nascimento

CPF não encontrado

Se o CPF não existir na base de dados, a resposta é 404 e não consome crédito:

JSON

{
  "success": false,
  "error": {
    "code": "CPF_NOT_FOUND",
    "message": "CPF not found in our database"
  }
}

✦

CPFs não encontrados não consomem créditos

Somente consultas bem-sucedidas (HTTP 200 com success: true) consomem 1 crédito do seu plano.

Limites de taxa

Plano	Limite
Gratuito	1 requisição a cada 2 segundos
Starter, Pro, Business	1 requisição por segundo
Enterprise	Sob consulta

Quando o limite é excedido, a API retorna HTTP 429 Too Many Requests.

Códigos de status

Status	Descrição
`200 OK`	Consulta bem-sucedida
`400 Bad Request`	CPF com formato inválido
`401 Unauthorized`	API Key ausente ou inválida
`403 Forbidden`	API Key suspensa
`404 Not Found`	CPF não encontrado (sem consumo de crédito)
`422 Unprocessable Entity`	CPF com dígitos verificadores inválidos
`429 Too Many Requests`	Limite de taxa excedido
`500 Internal Server Error`	Erro interno - reporte em caso de persistência

Para a lista completa de códigos de erro e mensagens, veja Códigos de Erro.

Atualizado em 12 de maio de 2026