# API de CPF: como funciona a consulta por faixa etária e gênero > Entenda como usar os dados de faixa etária e gênero retornados pela API de CPF para segmentação, compliance e prevenção de fraudes. **Publicado:** 22/04/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/api-de-cpf-como-funciona-a-consulta-por-faixa-etaria-e-genero --- A API de CPF retorna, além do nome do titular, a data de nascimento (dividida em dia, mês e ano) e o gênero — campos que permitem verificar maioridade, segmentar usuários por faixa etária e detectar inconsistências cadastrais automaticamente. Cada consulta ao endpoint `GET https://api.cpfhub.io/cpf/{CPF}` devolve esses dados em tempo real, com latência média de ~900ms. De acordo com a [Receita Federal](https://www.receita.fazenda.gov.br), o CPF concentra os registros cadastrais oficiais de pessoas físicas no Brasil, tornando esses dados a fonte mais confiável para validação de identidade. --- ## Dados retornados pela API A resposta da API inclui os seguintes campos relacionados a idade e gênero: ```json { "success": true, "data": { "cpf": "12345678900", "name": "Ana Paula Ferreira", "nameUpper": "ANA PAULA FERREIRA", "gender": "F", "birthDate": "22/08/1992", "day": 22, "month": 8, "year": 1992 } } ``` | Campo | Tipo | Descrição | | --- | --- | --- | | gender | String | Gênero do titular (M ou F) | | birthDate | String | Data de nascimento no formato DD/MM/YYYY | | day | Number | Dia de nascimento | | month | Number | Mês de nascimento | | year | Number | Ano de nascimento | Os campos `day`, `month` e `year` facilitam o cálculo de idade sem necessidade de parsear a string `birthDate`. --- ## Verificação de maioridade Um dos usos mais comuns dos dados de data de nascimento é a verificação de maioridade. Plataformas de apostas, e-commerces de bebidas alcoólicas e serviços financeiros precisam confirmar que o usuário tem 18 anos ou mais. ```python import requests from datetime import date def verificar_maioridade(cpf: str) -> dict: 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) resultado = response.json() if not resultado.get('success'): return {'maioridade': None, 'motivo': 'CPF nao encontrado'} dados = resultado['data'] hoje = date.today() nascimento = date(dados['year'], dados['month'], dados['day']) idade = hoje.year - nascimento.year # Ajuste se ainda nao fez aniversario no ano if (hoje.month, hoje.day) < (nascimento.month, nascimento.day): idade -= 1 return { 'maioridade': idade >= 18, 'idade': idade, 'nome': dados['name'], 'genero': dados['gender'] } resultado = verificar_maioridade('12345678900') print(resultado) # {'maioridade': True, 'idade': 33, 'nome': 'Ana Paula Ferreira', 'genero': 'F'} ``` --- ## Segmentação por faixa etária Para aplicações de marketing, CRM e análise de dados, a segmentação por faixa etária permite personalizar a experiência do usuário. ```python def classificar_faixa_etaria(ano_nascimento: int) -> str: idade = date.today().year - ano_nascimento if idade < 18: return 'Menor de idade' elif idade <= 25: return '18-25' elif idade <= 35: return '26-35' elif idade <= 45: return '36-45' elif idade <= 55: return '46-55' elif idade <= 65: return '56-65' else: return '65+' def enriquecer_cadastro(cpf: str) -> dict: 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) resultado = response.json() if not resultado.get('success'): return {'erro': 'CPF nao encontrado'} dados = resultado['data'] return { 'nome': dados['name'], 'genero': dados['gender'], 'faixa_etaria': classificar_faixa_etaria(dados['year']), 'idade': date.today().year - dados['year'] } print(enriquecer_cadastro('12345678900')) # {'nome': 'Ana Paula Ferreira', 'genero': 'F', 'faixa_etaria': '26-35', 'idade': 33} ``` --- ## Verificação de consistência de gênero O campo `gender` pode ser usado para detectar inconsistências entre os dados informados pelo usuário e os registros oficiais. Essa verificação é útil em cenários de prevenção de fraudes. ```javascript async function verificarConsistencia(cpf, generoInformado) { 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 { consistente: false, motivo: 'CPF nao encontrado' }; } const generoOficial = resultado.data.gender; const generoConsistente = generoInformado.toUpperCase() === generoOficial; return { consistente: generoConsistente, generoInformado: generoInformado.toUpperCase(), generoOficial, motivo: generoConsistente ? 'Genero confere' : 'Genero divergente' }; } catch (error) { clearTimeout(timeoutId); throw error; } } ``` --- ## Casos de uso por setor ### Plataformas de apostas e iGaming A regulamentação brasileira exige que plataformas de apostas verifiquem a maioridade dos apostadores. A API permite confirmar a idade do titular do CPF com base em dados oficiais, não apenas com base na declaração do usuário. ### E-commerce e marketplace Lojas que vendem produtos com restrição de idade (bebidas, tabaco, armas de pressão) podem integrar a verificação de maioridade diretamente no checkout, bloqueando pedidos de menores de idade automaticamente. ### Fintechs e bancos digitais Instituições financeiras podem usar a faixa etária e o gênero para oferecer produtos personalizados, além de detectar tentativas de fraude quando os dados informados divergem dos registros oficiais. ### Seguradoras O cálculo de prêmios de seguro frequentemente considera idade e gênero. A API permite automatizar a coleta desses dados no momento da cotação, eliminando erros de preenchimento. --- ## Análise de base de clientes Com os dados de faixa etária e gênero, é possível gerar relatórios sobre a composição da base de clientes. ```python from collections import Counter def analisar_base(lista_cpfs: list) -> dict: faixas = Counter() generos = Counter() headers = { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' } for cpf in lista_cpfs: url = f'https://api.cpfhub.io/cpf/{cpf}' response = requests.get(url, headers=headers, timeout=10) resultado = response.json() if resultado.get('success'): dados = resultado['data'] faixa = classificar_faixa_etaria(dados['year']) faixas[faixa] += 1 generos[dados['gender']] += 1 return { 'faixas_etarias': dict(faixas), 'generos': dict(generos), 'total_consultados': len(lista_cpfs) } ``` --- ## Boas práticas * **Calcule a idade com precisão** -- Use o dia e o mês para verificar se o titular já fez aniversário no ano corrente. Considerar apenas o ano pode gerar erros de até 1 ano. * **Não use gênero como fator de bloqueio** -- Divergência de gênero pode ter explicações legítimas (atualização cadastral em andamento). Use como sinal de alerta, não como critério único de rejeição. * **Respeite a LGPD** -- Os dados de faixa etária e gênero são dados pessoais. Use-os apenas para finalidades legítimas e declaradas ao titular. * **Cache os resultados** -- Se você precisa consultar múltiplos CPFs para análise, implemente cache para evitar consultas duplicadas e respeitar os rate limits. * **Considere o plano adequado** -- Para análises de base com muitos CPFs, o plano Pro (1.000 consultas/mês por R$ 149) ou o plano Corporativo são mais indicados. --- ## Perguntas frequentes ### Para que serve o campo `gender` retornado pela API de CPF? O campo `gender` indica o gênero do titular cadastrado na Receita Federal (valor `"M"` para masculino ou `"F"` para feminino). Ele é útil para detectar inconsistências entre os dados declarados pelo usuário e o registro oficial, o que pode sinalizar tentativas de uso de CPF de terceiros. Como sinal de fraude, deve ser combinado com outras verificações — nunca usado como critério único de bloqueio. ### Como calcular a idade a partir dos campos retornados pela API? A API devolve `day`, `month` e `year` separadamente para facilitar o cálculo. Use os três campos para verificar se o titular já fez aniversário no ano corrente: subtraia o ano de nascimento do ano atual e, se o par mês/dia atual for anterior ao par mês/dia de nascimento, subtraia mais 1. Considerar apenas o ano gera erros de até 12 meses. ### A API retorna dados de menores de idade? Sim, a API retorna os dados do titular independentemente da idade. A verificação de maioridade é responsabilidade da aplicação consumidora: basta calcular a idade a partir dos campos retornados e decidir se permite ou bloqueia o fluxo. Para plataformas com restrições legais de idade — como apostas e iGaming —, essa verificação é obrigatória por regulamentação. ### Quantas consultas posso fazer por mês para analisar minha base de clientes? O plano gratuito oferece 50 consultas mensais sem cartão de crédito, ideal para testes. Para análises de base de clientes, o plano Pro (R$149/mês) inclui 1.000 consultas. Se o limite for ultrapassado, a API não bloqueia: cobra R$0,15 por consulta adicional. Para volumes maiores, o plano Corporativo oferece cota personalizada. ### Leia também - [Diferença entre validação de CPF e consulta de CPF: quando usar cada uma](https://cpfhub.io/blog/diferenca-entre-validacao-de-cpf-e-consulta-de-cpf-quando-usar-cada-uma) - [Como funciona a consulta de CPF via API?](https://cpfhub.io/blog/como-funciona-a-consulta-de-cpf-na-base-da-receita-federal) - [Diferença entre validação sintática e validação real de CPF via API](https://cpfhub.io/blog/diferenca-entre-validacao-sintatica-e-validacao-real-de-cpf-via-api) - [Como consultar situação cadastral do CPF via API](https://cpfhub.io/blog/como-consultar-situacao-cadastral-do-cpf-via-api) --- ## Conclusão Os dados de faixa etária e gênero retornados pela API de CPF são ferramentas valiosas para verificação de maioridade, segmentação de público, prevenção de fraudes e compliance regulatório. A [**CPFHub.io**](https://www.cpfhub.io/) Cadastre-se em [cpfhub.io](https://www.cpfhub.io/)