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.

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 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
`GET`	`/cpf/{cpf}`	Consulta simples: nome, gênero e data de nascimento a partir da base da CPFHub.io
`POST`	`/cpf/realtime`	Consulta em tempo real na Receita Federal: situação cadastral e comprovante (1,5 crédito)
`POST`	`/cpf/bulk`	Consulta em lote, assíncrona
`GET`	`/cpf/bulk/{jobId}`	Status e resultados de um lote
`GET`	`/quota`	Saldo de créditos e plano

URL base

Todas as requisições devem usar HTTPS:

https://api.cpfhub.io

Requisições via http:// são redirecionadas automaticamente para HTTPS.

Formato das respostas

Todas as respostas usam Content-Type: application/json.

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 e error.message para exibir ou registrar o motivo. Erros de autenticação (401) e de créditos (403) trazem error como string:

JSON

{
  "success": false,
  "error": "Limite de créditos excedido"
}

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: cpfh_sua_api_key_aqui"

Obtenha sua chave gratuitamente em app.cpfhub.io.

Versão da API

A API está na versão v1. O número de versão não faz parte da URL - ele está implícito em todos os endpoints.

Próximos passos

Autenticação - detalhes sobre API Keys e segurança
Consulta de CPF - todos os campos e parâmetros
Limites de Requisições - cotas por plano
Códigos de Resposta - lista completa de erros

Atualizado em 2 de outubro de 2026