Introdução
A API do CPFHub.io permite consultar dados cadastrais vinculados a um CPF (nome, data de nascimento e gênero) em uma única requisição HTTP autenticada. Também consulta a situação cadastral direto na Receita Federal e processa listas de CPFs em lote.
O que você pode fazer
- Consultar nome completo, data de nascimento e gênero pelo número do CPF
- Verificar se um CPF possui dígitos verificadores válidos
- Calcular a idade do titular a partir de
year,montheday - Integrar verificação de maioridade ao seu fluxo de cadastro ou transação
- Consultar a situação cadastral e o ano do óbito do CPF na Receita Federal em tempo real, com código de controle e comprovante (Consulta em Tempo Real)
Endpoints
| Método | Endpoint | Descrição | Custo |
|---|---|---|---|
GET | /cpf/{cpf} | Consulta Simples: nome, gênero e data de nascimento a partir da base da CPFHub.io | 1 crédito por CPF encontrado |
POST | /cpf/realtime | Consulta em Tempo Real na Receita Federal: situação cadastral, ano do óbito (deathYear, inteiro ou null), código de controle e comprovante | 1,5 crédito por consulta bem-sucedida |
POST | /cpf/bulk | Consulta em lote, assíncrona, até 10.000 CPFs | 1 crédito por CPF encontrado |
GET | /cpf/bulk/{jobId} | Status e resultados de um lote | Grátis |
GET | /quota | Saldo de créditos, uso e plano | Grátis |
Os custos acima são os padrões. Consulte o custo específico da sua conta no dashboard.
URL base
Todas as requisições devem usar HTTPS:
https://api.cpfhub.ioRequisições via http:// recebem um redirecionamento 301 para HTTPS. Muitos clientes HTTP transformam um POST em GET ao seguir esse redirecionamento, então use sempre https:// direto.
Formato das respostas
As respostas da API usam Content-Type: application/json. A exceção é o comprovante (validationHtmlUrl), que é servido como text/html.
Sucesso (2xx):
{
"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
}
}Erro (4xx / 5xx):
{
"success": false,
"data": null,
"error": {
"message": "CPF não encontrado na base de dados"
}
}Use o status HTTP para decidir o fluxo. A maioria dos erros traz error.message. Erros de autenticação e de conta (401 e 403 de conta bloqueada), 500 "Erro ao validar assinatura" e 503 "usage_unavailable" trazem error como string:
{
"success": false,
"error": "API Key não fornecida"
}Para ler a mensagem nos dois formatos: typeof body.error === 'string' ? body.error : body.error?.message. A lista completa está em Códigos de Erro.
Autenticação
Todas as requisições precisam do header x-api-key com sua API Key:
curl "https://api.cpfhub.io/cpf/12345678909" \
-H "x-api-key: SUA_API_KEY"Obtenha sua chave gratuitamente em app.cpfhub.io/api-keys. A chave é uma string opaca: não dependa de prefixo ou formato.
Próximos passos
- Autenticação: API Keys e segurança
- Consulta Simples: campos, parâmetros e exemplos
- Consulta em Tempo Real: situação cadastral, ano do óbito e comprovante da Receita Federal
- Consulta em Lote: até 10.000 CPFs por requisição
- Saldo de Créditos: saldo, uso e plano da sua conta
- Limites de Uso: créditos por plano e limite por minuto
- Códigos de Erro: lista completa de erros e quando repetir
Atualizado em 3 de outubro de 2026