Um lead chega com informação mínima — às vezes só um telefone, um email ou um CPF. O endpoint POST /leads/enriquecer transforma esse fragmento em um perfil rico com nome, localização, scoring de renda, vínculos empresariais e contatos — em uma única chamada.

​
O problema

Sem enriquecimento, o vendedor não sabe se está falando com um estagiário ou um diretor, se a empresa fatura milhões ou está baixada, se o lead tem poder de decisão ou não.

​
Como funciona

​
Resolução de Identidade

O endpoint aceita 3 tipos de identificador e resolve automaticamente para CPF:
IdentificadorResolução
CPFDireto (valida formato)
Telefonepessoas.cpf_by_telefone → CPF
Emailpessoas.cpf_by_email → CPF, fallback via empresa → sócio

​
Dados Retornados

CampoDescriçãoExemplo
nomeNome completoJoão Silva
data_nascimentoData de nascimento1985-03-15
sexoSexoM
score_rendaScoring de renda (faixa A-E){ faixa: "B", score: 62 }
contatos.telefonesTelefones vinculados[“11987654321”]
contatos.emailsEmails vinculados[“[email protected]”]
enderecoEndereço principal{ cidade: "São Paulo", uf: "SP" }
empresasParticipações societáriasCNPJ, cargo, capital
patrimonio_resumoResumo patrimonialImóveis, veículos, valores
remuneracao_atualRemuneração ativa12000

​
Antes vs Depois

Antes (lead cru)Depois (enriquecido)
Telefone: 11987654321Nome: Maria Silva Santos
—Score: B (Alta renda)
—2 imóveis (R$850k), 1 veículo
—Sócia-administradora da Tech Ltda (R$500k)
—Remuneração: R$12.000
—Email: [email protected]

​
Exemplo de Uso

import requests

# Enriquecer 3 leads de uma vez
response = requests.post(
    "https://modulos.sherlocker.dev/leads/enriquecer",
    params={"token": "SEU_TOKEN"},
    json={
        "contatos": [
            {"cpf": "12345678901"},
            {"telefone": "11987654321"},
            {"email": "[email protected]"}
        ],
        "campos": ["identidade", "renda", "contatos", "empresas"]
    }
)

data = response.json()
print(f"Enriquecidos: {data['enriquecidos']}/{data['total']}")

for r in data["resultados"]:
    if r["status"] == "ok":
        print(f"  {r['nome']} - Faixa {r['score_renda']['faixa']} (Score {r['score_renda']['score']})")
        print(f"  Sinais: {', '.join(r['score_renda']['sinais'])}")

​
Limites e Modo Assíncrono

ModoMax contatosComo usar
Síncrono100POST /leads/enriquecer
Assíncrono1.000POST /leads/async/enriquecer → poll GET /leads/jobs/{jobId}

​
Exemplo assíncrono

# Lote grande — usar async
response = requests.post(
    "https://modulos.sherlocker.dev/leads/async/enriquecer",
    params={"token": "SEU_TOKEN"},
    json={"contatos": lista_de_500_leads}
)

job = response.json()
print(f"Job criado: {job['jobId']}")
print(f"Acompanhar em: {job['statusUrl']}")

# Poll ate completar
import time
while True:
    status = requests.get(
        f"https://modulos.sherlocker.dev{job['statusUrl']}",
        params={"token": "SEU_TOKEN"}
    ).json()
    if status["status"] in ("completed", "failed"):
        break
    time.sleep(5)

resultados = status["result"]

​
Campos Selecionáveis

Use o parâmetro campos para retornar apenas os dados necessários:
  • identidade — nome, data_nascimento, sexo, endereço
  • renda — score_renda, patrimonio_resumo, remuneração
  • contatos — telefones e emails
  • empresas — participações societárias
Omitir campos retorna todos os dados.

​
APIs utilizadas

Enriquecer

Enriquecimento síncrono (max 100)

Enriquecer Async

Enriquecimento assíncrono (max 1.000)

Pessoas

Identidade e contatos

Empresas

Vínculos societários

Imóveis

Patrimônio imobiliário

Veículos

Frota de veículos

​
Conexão entre entidades