# Como usar API de CPF para enriquecer dados de CRM automaticamente > Aprenda a usar a API de CPF para enriquecer automaticamente os dados do seu CRM com nome completo, data de nascimento e gênero dos contatos. **Publicado:** 14/05/2026 **Autor:** Redação CPFHub.io **URL:** https://cpfhub.io/blog/como-usar-api-de-cpf-para-enriquecer-dados-de-crm-automaticamente --- Para enriquecer dados de CRM com a API de CPF da CPFHub.io, faça uma chamada GET para `https://api.cpfhub.io/cpf/{CPF}` com a API key no header `x-api-key`. A resposta retorna nome completo, data de nascimento e gênero em ~900ms — dados que preenchem automaticamente os campos vazios ou incompletos de cada contato na base. Consultas excedentes ao plano nunca bloqueiam: são cobradas a R$0,15 cada. A qualidade dos dados em um CRM impacta diretamente a eficiência da equipe comercial, a personalização de campanhas de marketing e a precisão de relatórios gerenciais. Muitas empresas possuem bases de contatos com informações incompletas ou desatualizadas — nomes abreviados, datas de nascimento ausentes, gênero não preenchido. Enriquecer esses dados manualmente é inviável em bases com milhares de registros. --- ## O que significa enriquecer dados de CRM Enriquecimento de dados é o processo de complementar registros existentes com informações adicionais obtidas de fontes externas. No contexto de CRM, isso significa usar o CPF do contato para buscar dados cadastrais oficiais. ### Dados disponíveis via API A API da CPFHub.io retorna os seguintes campos para cada CPF consultado: ```json { "success": true, "data": { "cpf": "12345678900", "name": "Carla Mendes Oliveira", "nameUpper": "CARLA MENDES OLIVEIRA", "gender": "F", "birthDate": "08/11/1988", "day": 8, "month": 11, "year": 1988 } } ``` ### O que pode ser enriquecido | Campo no CRM | Antes | Depois (via API) | | --- | --- | --- | | Nome | C. Oliveira | Carla Mendes Oliveira | | Data de nascimento | (vazio) | 08/11/1988 | | Gênero | (vazio) | F | | Faixa etária | (vazio) | 36-45 | --- ## Implementação do enriquecimento em Python O script a seguir lê uma lista de contatos, consulta a API para cada CPF e atualiza os campos ausentes. ```python import requests import csv import time from datetime import date CPFHUB_API_KEY = 'SUA_CHAVE_DE_API' def consultar_cpf(cpf: str) -> dict: url = f'https://api.cpfhub.io/cpf/{cpf}' headers = { 'x-api-key': CPFHUB_API_KEY, 'Accept': 'application/json' } response = requests.get(url, headers=headers, timeout=10) return response.json() def classificar_faixa_etaria(ano: int) -> str: idade = date.today().year - ano if idade <= 25: return '18-25' elif idade <= 35: return '26-35' elif idade <= 45: return '36-45' elif idade <= 55: return '46-55' else: return '55+' def enriquecer_contatos(arquivo_entrada: str, arquivo_saida: str): contatos_atualizados = [] total = 0 enriquecidos = 0 erros = 0 with open(arquivo_entrada, 'r', encoding='utf-8') as f: leitor = csv.DictReader(f) for contato in leitor: total += 1 cpf = contato.get('cpf', '').replace('.', '').replace('-', '') if not cpf or len(cpf) != 11: contatos_atualizados.append(contato) continue try: resultado = consultar_cpf(cpf) if resultado.get('success'): dados = resultado['data'] # Atualizar nome se estiver vazio ou abreviado if not contato.get('nome') or len(contato['nome']) < 10: contato['nome'] = dados['name'] # Preencher data de nascimento se vazia if not contato.get('data_nascimento'): contato['data_nascimento'] = dados['birthDate'] # Preencher genero se vazio if not contato.get('genero'): contato['genero'] = dados['gender'] # Calcular faixa etaria contato['faixa_etaria'] = classificar_faixa_etaria(dados['year']) enriquecidos += 1 else: erros += 1 except Exception as e: erros += 1 print(f'Erro ao consultar CPF {cpf}: {e}') contatos_atualizados.append(contato) # Intervalo entre requisições para bases grandes time.sleep(2) # Salvar arquivo enriquecido if contatos_atualizados: campos = contatos_atualizados[0].keys() with open(arquivo_saida, 'w', encoding='utf-8', newline='') as f: escritor = csv.DictWriter(f, fieldnames=campos) escritor.writeheader() escritor.writerows(contatos_atualizados) print(f'Total: {total} | Enriquecidos: {enriquecidos} | Erros: {erros}') enriquecer_contatos('contatos.csv', 'contatos_enriquecidos.csv') ``` --- ## Integração com CRMs populares ### Via API do CRM A maioria dos CRMs modernos oferece APIs para leitura e atualização de registros. O fluxo é: 1. Buscar contatos no CRM que possuem CPF mas têm campos incompletos. 2. Consultar a API da CPFHub.io para cada CPF. 3. Atualizar o registro no CRM via API. ### Via webhooks Outra abordagem é configurar um webhook que é disparado quando um novo contato é criado no CRM. O webhook aciona uma função que consulta a API e atualiza o registro automaticamente. ```javascript const express = require('express'); const app = express(); app.use(express.json()); app.post('/webhook/novo-contato', async (req, res) => { const { cpf, contatoId } = req.body; if (!cpf) { return res.json({ status: 'ignorado', motivo: 'CPF ausente' }); } const cpfLimpo = cpf.replace(/\D/g, ''); const controller = new AbortController(); const timeoutId = setTimeout(() => controller.abort(), 10000); try { const response = await fetch( `https://api.cpfhub.io/cpf/${cpfLimpo}`, { headers: { 'x-api-key': 'SUA_CHAVE_DE_API', 'Accept': 'application/json' }, signal: controller.signal } ); clearTimeout(timeoutId); const resultado = await response.json(); if (resultado.success) { // Aqui voce chamaria a API do seu CRM para atualizar o contato console.log(`Contato ${contatoId} enriquecido:`, resultado.data); return res.json({ status: 'enriquecido', dados: resultado.data }); } return res.json({ status: 'nao_encontrado' }); } catch (error) { clearTimeout(timeoutId); return res.status(500).json({ status: 'erro' }); } }); app.listen(3000); ``` --- ## Automatizando com agendamento Para enriquecer a base existente gradualmente, sem exceder os limites do plano, implemente um job agendado. ### Estratégia de processamento * **Plano Gratuito (50 consultas/mês)** — Processar 1-2 contatos por dia. * **Plano Pro (1.000 consultas/mês)** — Processar até 33 contatos por dia. * **Plano Corporativo** — Volume personalizado conforme a necessidade. ### Priorização Nem todos os contatos precisam ser enriquecidos com a mesma urgência. Priorize: 1. Contatos criados recentemente (leads ativos). 2. Contatos com campos críticos vazios (nome incompleto). 3. Contatos que serão alvo de campanhas próximas. 4. Restante da base, em ordem cronológica. --- ## Boas práticas * **Obtenha consentimento** — A LGPD exige base legal para o tratamento de dados pessoais. Garanta que o enriquecimento de dados está amparado pelo consentimento do titular ou por outra base legal aplicável. A [Autoridade Nacional de Proteção de Dados (ANPD)](https://www.gov.br/anpd) disponibiliza orientações sobre as bases legais previstas na Lei nº 13.709/2018. * **Não sobrescreva dados confirmados** — Se o contato já informou seus dados e eles foram confirmados, não sobrescreva automaticamente. Use os dados da API apenas para preencher campos vazios ou corrigir dados incompletos. * **Registre a origem dos dados** — Marque no CRM quais campos foram preenchidos via API, para rastreabilidade e auditoria. * **Insira intervalos entre consultas** — Em lotes grandes, adicione delays entre as requisições para distribuir o consumo ao longo do tempo. * **Valide antes de salvar** — Verifique se os dados retornados pela API são consistentes antes de atualizar o CRM. --- ## Perguntas frequentes ### É possível enriquecer uma base de CRM inteira de uma vez com a API de CPF? Sim, mas o ideal é fazer em lotes agendados. Para bases grandes, processe em batches diários conforme o volume do seu plano — 50 consultas/mês no Gratuito, 1.000 no Pro. Ao superar o limite, a API não bloqueia: consultas excedentes são cobradas a R$0,15 cada. Isso permite escalar o enriquecimento sem interrupção, ajustando o ritmo conforme o orçamento. ### Que campos a API retorna para enriquecer o CRM? Para cada CPF, a API retorna: nome completo, nome em maiúsculas, gênero (M/F), data de nascimento (dia, mês e ano separados). Com esses dados, é possível preencher nome, gênero, data de nascimento e calcular faixa etária automaticamente — eliminando a necessidade de formulários longos no cadastro. ### Como evitar sobrescrever dados que o próprio contato informou? Antes de atualizar o registro no CRM, verifique se o campo já está preenchido. No script Python da seção acima, o padrão é checar `if not contato.get('nome')` antes de substituir. Para campos como gênero, que o usuário pode ter informado corretamente, adicione uma flag `enriquecido_via_api` para distinguir dados fornecidos pelo titular de dados vindos da consulta. ### O enriquecimento de dados de CRM com CPF é permitido pela LGPD? Sim, desde que haja base legal. As mais usadas nesse contexto são consentimento (Art. 7, I) — quando o contato aceitou os termos ao se cadastrar — e legítimo interesse (Art. 7, IX) — quando o enriquecimento é necessário para a finalidade comercial do tratamento. Documente a base legal adotada e inclua essa finalidade na política de privacidade. ### Leia também - [Como integrar API de CPF com Zapier e Make (Integromat) sem código](https://cpfhub.io/blog/como-integrar-api-de-cpf-com-zapier-e-make-sem-codigo) - [Como consumir API de CPF em Notion com integrações via API](https://cpfhub.io/blog/como-consumir-api-de-cpf-em-notion-com-integracoes-via-api) - [Como integrar API de CPF em chatbots do WhatsApp Business](https://cpfhub.io/blog/como-integrar-api-de-cpf-em-chatbots-do-whatsapp-business) - [Como integrar API de CPF em ERPs open source (Odoo, ERPNext)](https://cpfhub.io/blog/como-integrar-api-de-cpf-em-erps-open-source-odoo-erpnext) --- ## Conclusão Enriquecer dados de CRM com informações de CPF é uma forma eficiente de melhorar a qualidade da base de contatos, personalizar o atendimento e aumentar a eficácia das campanhas de marketing. Com a API da CPFHub.io, o processo pode ser totalmente automatizado — seja via webhook no cadastro de novos leads, seja via job agendado para sanitizar a base existente. O resultado é um CRM mais completo sem exigir que os contatos preencham formulários longos. A latência média de ~900ms permite integrar a consulta ao fluxo de onboarding sem impacto perceptível para o usuário. O plano gratuito cobre os primeiros 50 testes sem cartão; o plano Pro garante 1.000 consultas mensais para operações em escala. Consultas acima do limite nunca bloqueiam — são cobradas automaticamente a R$0,15 cada. Crie sua conta em [cpfhub.io](https://www.cpfhub.io/) e comece a enriquecer sua base de CRM hoje mesmo.