Quais informações são retornadas por uma API de consulta de CPF?

Uma API de consulta de CPF retorna, no mínimo, o nome completo do titular, a data de nascimento e o gênero — todos em formato JSON. A CPFHub.io retorna sete campos: cpf, name, nameUpper, gender, birthDate, day, month e year, com latência de ~900ms. Esses dados são suficientes para KYC, verificação de idade, preenchimento automático de formulários e emissão de notas fiscais.

Introdução

Ao integrar uma API de consulta de CPF, uma das primeiras perguntas é: quais dados ela retorna? Entender o formato e o conteúdo da resposta é essencial para planejar a integração e definir como esses dados serão utilizados no seu sistema.

Formato da resposta

A API retorna os dados em formato JSON padronizado:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "João da Silva",
    "nameUpper": "JOÃO DA SILVA",
    "gender": "M",
    "birthDate": "15/06/1990",
    "day": 15,
    "month": 6,
    "year": 1990
    }
}

Detalhamento de cada campo

success

• Tipo: boolean
• Descrição: Indica se a consulta foi bem-sucedida.
• Uso: Verificar se o CPF foi encontrado antes de acessar os demais campos.

cpf

• Tipo: string (11 dígitos, sem formatação)
• Descrição: O número do CPF consultado.
• Uso: Confirmação e referência cruzada.

name

• Tipo: string
• Descrição: Nome completo do titular do CPF.
• Uso: Preenchimento automático de formulários, cruzamento com nome informado pelo usuário, KYC.

nameUpper

• Tipo: string
• Descrição: Nome completo em letras maiúsculas.
• Uso: Padronização em sistemas que exigem nomes em caixa alta (NF-e, boletos, documentos oficiais).

gender

• Tipo: string ("M" ou "F")
• Descrição: Gênero do titular.
• Uso: Personalização de comunicação, segmentação de dados, validação complementar.

birthDate

• Tipo: string (formato DD/MM/YYYY)
• Descrição: Data de nascimento completa.
• Uso: Verificação de idade (18+), KYC, cruzamento de dados.

day, month, year

• Tipo: number
• Descrição: Dia, mês e ano de nascimento como campos numéricos separados.
• Uso: Cálculos de idade, filtros por faixa etária, lógica condicional sem parsing de string.

Exemplos de uso prático por setor

Como acessar os dados

Faça uma requisição GET ao endpoint:

curl -X GET https://api.cpfhub.io/cpf/12345678900 \
    -H "x-api-key: SUA_CHAVE_DE_API" \
    -H "Accept: application/json"

E processe a resposta na linguagem da sua escolha. Exemplo em JavaScript:

const response = await fetch('https://api.cpfhub.io/cpf/12345678900', {
    headers: {
    'x-api-key': process.env.CPFHUB_API_KEY,
    'Accept': 'application/json'
    }
});

const resultado = await response.json();

if (resultado.success) {
    console.log('Nome:', resultado.data.name);
    console.log('Nascimento:', resultado.data.birthDate);
    console.log('Genero:', resultado.data.gender);
}

Todos os planos retornam os mesmos dados?

Sim. A CPFHub.io retorna o mesmo conjunto de dados em todos os planos — do gratuito ao corporativo. A diferença entre planos está no volume de consultas, SLA e nível de suporte:

Perguntas frequentes

A API retorna o status do CPF (ativo, suspenso, cancelado)?

A CPFHub.io retorna os dados cadastrais do titular — nome, data de nascimento e gênero. O campo success: true confirma que o CPF existe e foi localizado na base. Para verificação específica de situação cadastral (ativo/suspenso/cancelado), consulte diretamente o portal da Receita Federal, que oferece esse serviço gratuitamente.

O campo gender é confiável para personalização de comunicação?

O campo gender reflete o gênero registrado no CPF, que em muitos casos corresponde ao sexo de nascimento. Para comunicações sensíveis, especialmente com públicos que podem ter nome social diferente do nome civil, use o dado como referência inicial e ofereça ao usuário a opção de corrigir no perfil. A ANPD orienta que dados sensíveis como identidade de gênero devem ser tratados com base legal específica.

Por que a API retorna day, month e year separados além de birthDate?

O campo birthDate retorna a data no formato DD/MM/YYYY como string, o que exige parsing para cálculos. Os campos numéricos separados (day, month, year) eliminam essa etapa: você pode calcular a idade com subtração direta, filtrar por faixa etária com comparação numérica ou construir consultas SQL sem conversão de formato.

Quantas consultas gratuitas estão disponíveis e o que acontece ao esgotar?

O plano gratuito oferece 50 consultas por mês sem cartão de crédito. Ao ultrapassar esse limite, a API não bloqueia: cada consulta adicional é cobrada a R$0,15 automaticamente. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149, também com R$0,15 por consulta excedente sem interrupção do serviço.

Conclusão

A API da CPFHub.io retorna um conjunto completo de dados cadastrais — nome, data de nascimento, gênero e campos numéricos separados — no mesmo formato independente do plano contratado. Isso garante que a integração feita no plano gratuito funcione sem alterações ao migrar para o Pro.

Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e explore todos os campos retornados pela API no seu próximo projeto.