# Quais informações são retornadas por uma API de consulta de CPF? > Descubra quais informações são retornadas por uma API de consulta de CPF. Veja os campos disponíveis, formato JSON e como usar cada dado. **Publicado:** 05/05/2025 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/quais-informacoes-retornadas-api-consulta-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**: ```json { "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 | Setor | Campos mais usados | Finalidade | | --- | --- | --- | | E-commerce | name, cpf | Validar comprador no checkout | | Fintechs | name, cpf, birthDate | KYC e abertura de conta | | Seguradoras | name, birthDate, gender | Cálculo de risco e prêmio | | Marketplaces | name, cpf | Validar vendedores | | Apostas/iGaming | birthDate, year | Verificação de idade (18+) | | ERP/NF-e | nameUpper, cpf | Emissão de notas fiscais | --- ## Como acessar os dados Faça uma requisição GET ao endpoint: ```bash 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: ```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: | Plano | Consultas/mês | Dados retornados | SLA | | --- | --- | --- | --- | | Gratuito | 50 | Completos | 80% | | Pro (R$ 149/mês) | 1.000 | Completos | 99% | | Corporativo | Personalizado | Completos | 99,9% | --- ## 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](https://servicos.receita.fazenda.gov.br/Servicos/CPF/ConsultaSituacao/ConsultaPublica.asp), 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](https://www.gov.br/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. ### 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) - [API de CPF grátis para desenvolvedores: como começar em 5 minutos](https://cpfhub.io/blog/api-cpf-gratis-desenvolvedores-comecar-5-minutos) - [Onboarding digital em fintechs: como validar CPF em menos de 30 segundos](https://cpfhub.io/blog/onboarding-digital-em-fintechs-como-validar-cpf-em-menos-de-30-segundos) - [KYC no Brasil: quais setores são obrigados a validar CPF por lei](https://cpfhub.io/blog/kyc-no-brasil-quais-setores-sao-obrigados-a-validar-cpf-por-lei) --- ## 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](https://www.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.