CPFHub.io

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, month e day
  • 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étodoEndpointDescriçãoCusto
GET/cpf/{cpf}Consulta Simples: nome, gênero e data de nascimento a partir da base da CPFHub.io1 crédito por CPF encontrado
POST/cpf/realtimeConsulta em Tempo Real na Receita Federal: situação cadastral, ano do óbito (deathYear, inteiro ou null), código de controle e comprovante1,5 crédito por consulta bem-sucedida
POST/cpf/bulkConsulta em lote, assíncrona, até 10.000 CPFs1 crédito por CPF encontrado
GET/cpf/bulk/{jobId}Status e resultados de um loteGrátis
GET/quotaSaldo de créditos, uso e planoGrá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.io

Requisiçõ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):

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

Erro (4xx / 5xx):

JSON
{
  "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:

JSON
{
  "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:

bash
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


Atualizado em 3 de outubro de 2026