API de CPF: como consultar data de nascimento pelo número do documento

A API da CPFHub.io permite consultar a data de nascimento associada a um CPF com uma única chamada GET autenticada. A resposta retorna a data completa no campo birthDate (formato DD/MM/YYYY) e também os campos numéricos day, month e year, prontos para cálculos de idade sem parsing manual — com latência de aproximadamente 900ms.

Introdução

Consultar a data de nascimento associada a um CPF é uma necessidade comum em processos de verificação de identidade, validação de idade mínima e prevenção de fraudes. Plataformas de e-commerce, fintechs, casas de apostas e sistemas de saúde frequentemente precisam confirmar a idade do titular do documento antes de autorizar operações.

Quando a data de nascimento do CPF é necessária?

A consulta à data de nascimento vinculada a um CPF atende a diversas necessidades de negócio:

• Verificação de idade mínima -- Plataformas de apostas e serviços financeiros precisam confirmar que o usuário tem 18 anos ou mais antes de liberar o acesso.

• Processos de KYC -- O cruzamento da data de nascimento informada pelo usuário com a data oficial ajuda a detectar tentativas de fraude no cadastro.

• Segmentação de clientes -- A faixa etária do titular pode ser usada para personalizar ofertas e comunicações.

• Conformidade regulatória -- Setores regulados exigem a verificação de dados cadastrais como parte dos processos de compliance.

Como a API retorna a data de nascimento

A API da CPFHub.io retorna os dados de nascimento em três campos distintos, facilitando tanto a exibição formatada quanto cálculos programáticos de idade.

Campos relacionados à data de nascimento

Essa estrutura facilita tanto a exibição formatada quanto cálculos programáticos de idade, sem necessidade de parsing manual da string.

Exemplo de consulta com cURL

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

Resposta:

{
    "success": true,
    "data": {
    "cpf": "12345678900",
    "name": "Maria Oliveira",
    "nameUpper": "MARIA OLIVEIRA",
    "gender": "F",
    "birthDate": "22/03/1985",
    "day": 22,
    "month": 3,
    "year": 1985
    }
}

Implementação em JavaScript com cálculo de idade

O exemplo abaixo consulta o CPF via API e calcula a idade do titular a partir dos campos numéricos retornados:

async function consultarIdadePorCPF(cpf) {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), 10000);

    try {
    const response = await fetch(
    `https://api.cpfhub.io/cpf/${cpf}`,
    {
    headers: {
    'x-api-key': 'SUA_CHAVE_DE_API',
    'Accept': 'application/json'
    },
    signal: controller.signal
    }
    );

    clearTimeout(timeoutId);
    const resultado = await response.json();

    if (!resultado.success) {
    return { erro: 'CPF não encontrado' };
    }

    const { day, month, year } = resultado.data;
    const hoje = new Date();
    let idade = hoje.getFullYear() - year;

    if (
    hoje.getMonth() + 1 < month ||
    (hoje.getMonth() + 1 === month && hoje.getDate() < day)
    ) {
    idade--;
    }

    return {
    nome: resultado.data.name,
    dataNascimento: resultado.data.birthDate,
    idade
    };
    } catch (error) {
    if (error.name === 'AbortError') {
    return { erro: 'Timeout na requisição' };
    }
    return { erro: error.message };
    }
}

// Uso
consultarIdadePorCPF('12345678900').then(console.log);

Implementação em Python com verificação de idade mínima

import requests
from datetime import date

def verificar_idade_minima(cpf, idade_minima=18):
    url = f"https://api.cpfhub.io/cpf/{cpf}"
    headers = {
    "x-api-key": "SUA_CHAVE_DE_API",
    "Accept": "application/json"
    }

    response = requests.get(url, headers=headers, timeout=10)
    dados = response.json()

    if not dados.get("success"):
    return {"aprovado": False, "motivo": "CPF não encontrado"}

    ano = dados["data"]["year"]
    mes = dados["data"]["month"]
    dia = dados["data"]["day"]

    nascimento = date(ano, mes, dia)
    hoje = date.today()
    idade = hoje.year - nascimento.year

    if (hoje.month, hoje.day) < (nascimento.month, nascimento.day):
    idade -= 1

    if idade < idade_minima:
    return {
    "aprovado": False,
    "motivo": f"Idade {idade} abaixo do mínimo de {idade_minima}"
    }

    return {
    "aprovado": True,
    "nome": dados["data"]["name"],
    "idade": idade
    }

# Uso
resultado = verificar_idade_minima("12345678900")
print(resultado)

Casos de uso por setor

Plataformas de apostas e iGaming

A regulamentação de apostas online no Brasil exige que todos os apostadores tenham pelo menos 18 anos. A consulta à data de nascimento via API permite automatizar essa verificação no momento do cadastro, sem depender de upload de documentos.

Fintechs e bancos digitais

Na abertura de contas digitais, a data de nascimento é um dos campos obrigatórios para processos de KYC. A comparação entre a data informada pelo usuário e a data oficial retornada pela API é uma camada adicional de segurança contra fraudes.

E-commerce

Em compras de produtos com restrição de idade (bebidas alcoólicas, por exemplo), a consulta pode ser feita no checkout para confirmar que o comprador atende aos requisitos legais.

Sistemas de saúde

Hospitais e clínicas podem usar a data de nascimento para confirmar a identidade do paciente e calcular a faixa etária para fins de triagem ou dosagem de medicamentos.

Boas práticas ao consultar data de nascimento via API

• Valide o CPF sintaticamente antes da consulta -- Verifique os dígitos verificadores localmente para evitar requisições desnecessárias à API.

• Use os campos numéricos para cálculos -- Os campos day, month e year são mais confiáveis para cálculos de idade do que o parsing da string birthDate.

• Armazene apenas o necessário -- Em conformidade com a LGPD, armazene somente os dados que sua aplicação realmente precisa. Se apenas a verificação de idade é necessária, não é preciso guardar a data completa.

• Configure timeout nas requisições -- Sempre defina um timeout (recomendado: 10 segundos) para evitar travamentos na aplicação.

• Trate o cenário de CPF não encontrado -- Nem todo CPF retornará dados. Implemente fallbacks adequados para esse cenário.

Perguntas frequentes

O que é necessário para implementar validação de CPF neste contexto?

A validação de CPF exige uma chamada à API com o número do documento e a chave de autenticação. A CPFHub.io retorna o status do CPF, nome do titular e data de nascimento em menos de 200ms, permitindo a verificação em tempo real durante o cadastro ou transação.

A API CPFHub.io funciona para todos os volumes de consulta?

Sim. O plano gratuito oferece 50 consultas por mês sem cartão de crédito — ideal para testes e projetos pequenos. Para volumes maiores, o plano Pro inclui 1.000 consultas mensais por R$149. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional.

Como garantir conformidade com a LGPD ao usar uma API de CPF?

Use o CPF apenas para a finalidade declarada ao titular, armazene apenas o necessário (não guarde o CPF cru se um token bastar), implemente controle de acesso aos logs de consulta e documente a base legal para o tratamento. A ANPD orienta que dados de identificação devem ser tratados com o princípio da necessidade.

Quanto tempo leva para integrar a API CPFHub.io?

A integração básica leva menos de 30 minutos: crie uma conta em cpfhub.io, gere a API key no painel e faça uma chamada GET para https://api.cpfhub.io/cpf/{CPF} com o header x-api-key. A documentação inclui exemplos em Python, Node.js, PHP, Java e outras linguagens.

Conclusão

A consulta à data de nascimento pelo número do CPF é um recurso valioso para verificação de idade, prevenção de fraudes e processos de KYC. A API da CPFHub.io retorna os campos birthDate, day, month e year em uma única chamada, tornando o cálculo de idade direto e seguro para qualquer linguagem ou plataforma.

Com tempo de resposta de aproximadamente 900ms e plano gratuito com 50 consultas por mês sem cartão de crédito, a integração pode ser testada imediatamente. Cadastre-se em cpfhub.io — 50 consultas mensais gratuitas, sem cartão de crédito — e comece a verificar idades e validar identidades em tempo real nos seus fluxos de cadastro.