Documentação da API

Envie um CPF ou CNPJ e receba os telefones relacionados, já ordenados do maior para o menor score. Uma requisição HTTP, resposta em JSON.

curl -H "Authorization: Bearer SUA_API_KEY" "https://api.addlead.com.br/doc_number/12345678909"

Visão geral

Não há SDK a instalar nem sessão a manter: qualquer linguagem que faça uma requisição HTTP integra com o addLead. Na prática, isso torna a API compatível com CRMs, PABX e discadores como Asterisk e VICIdial.

Autenticação

Toda consulta exige uma API key. Você pode enviá-la de três formas — a primeira encontrada é usada, nesta ordem:

A API key tem de 8 a 128 caracteres, entre letras, números, hífen e sublinhado (^[A-Za-z0-9\-_]{8,128}$). Chaves no formato legado (999999A-AAAA-9999-AA99-A9999A9999AA) continuam válidas, e a caixa das letras não importa. O header X-Api-Token mantém esse nome por compatibilidade.

Ainda não tem uma API key? Solicite o acesso e a chave é enviada por e-mail. Suas API keys ficam disponíveis no portal do cliente.

Consultar documento

Retorna os telefones relacionados a um CPF ou CNPJ.

Parâmetro de caminho

Exemplos

curl -H "Authorization: Bearer SUA_API_KEY" "https://api.addlead.com.br/doc_number/12345678909"

curl "https://api.addlead.com.br/doc_number/12345678909?api_key=SUA_API_KEY"

const doc = "12345678909";

const res = await fetch(`https://api.addlead.com.br/doc_number/${doc}`, {
  headers: { "X-Api-Token": process.env.ADDLEAD_API_KEY },
});

const data = await res.json();

if (!res.ok) {
  throw new Error(`addLead ${res.status}: ${data.error}`);
}

console.log(data.count, data.phones);

$doc = '12345678909';

$ch = curl_init("https://api.addlead.com.br/doc_number/{$doc}");
curl_setopt_array($ch, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER     => ['X-Api-Token: ' . getenv('ADDLEAD_API_KEY')],
    CURLOPT_TIMEOUT        => 10,
]);

$body   = curl_exec($ch);
$status = curl_getinfo($ch, CURLINFO_RESPONSE_CODE);
curl_close($ch);

$data = json_decode($body, true);

if ($status !== 200) {
    throw new RuntimeException("addLead {$status}: {$data['error']}");
}

print_r($data['phones']);

import os
import requests

doc = "12345678909"

res = requests.get(
    f"https://api.addlead.com.br/doc_number/{doc}",
    headers={"X-Api-Token": os.environ["ADDLEAD_API_KEY"]},
    timeout=10,
)

data = res.json()

if res.status_code != 200:
    raise RuntimeError(f"addLead {res.status_code}: {data['error']}")

print(data["count"], data["phones"])

Resposta

Sucesso — 200 OK

{
  "document": "12345678909",
  "phones": ["31999999999", "31999999998", "31999999997"],
  "count": 3
}

Sem resultado — 200 OK

Um documento sem telefones na base não é erro: a resposta é 200 com lista vazia.

{ "document": "12345678909", "phones": [], "count": 0 }

Erros

Todo erro retorna JSON no formato {"error": "<mensagem>"}.

{ "error": "API key inválida" }

Limites de uso

• 30 requisições por segundo por IP. Acima disso o servidor responde 503 até a taxa normalizar. Para volumes altos, distribua as consultas ao longo do tempo, use a consulta em lote ou fale com a gente sobre um limite dedicado.
• Consulta sem resultado não consome crédito. Um 200 com count: 0 não desconta nada do seu saldo.
• Saldo esgotado. Quando o saldo acaba, a API passa a responder 429. O saldo é da conta: todas as suas API keys consomem do mesmo pool. Acompanhe o consumo e o saldo no portal do cliente; para comprar mais volume, fale com a nossa equipe.
• O que não conta. HEAD, OPTIONS e respostas 404 ou 405 não entram no seu consumo.
• Timeout. A consulta responde em poucos milissegundos; um timeout de 10 segundos no seu cliente é folgado o bastante.

Métodos

Os endpoints aceitam GET, HEAD e OPTIONS. Qualquer outro método em uma rota existente responde 405 com o header Allow: GET, HEAD, OPTIONS — enquanto uma rota inexistente responde 404, para não confirmar quais rotas existem.

curl -I -H "Authorization: Bearer SUA_API_KEY" "https://api.addlead.com.br/doc_number/12345678909"

Consulta em lote

Para enriquecer uma base inteira sem escrever código, existe a consulta em lote: fale com a nossa equipe para habilitar. O envio é feito pelo portal do cliente, na aba Arquivos. O processamento é assíncrono — você envia o arquivo, ele é processado em segundo plano e o resultado fica disponível para download.

Arquivo enviado

10370197636
10421945822
15765863589

Arquivo devolvido

10370197636,31971807969,31979521597,31951462597
10421945822,31989751325
15765863589

Boas práticas

• Guarde a API key fora do código. Use variável de ambiente ou cofre de segredos — nunca versione a chave no repositório.
• Limpe o documento antes de montar a URL. Remova pontos, traços, barras e espaços; envie apenas dígitos.
• Trate o 200 com count: 0. É o caso mais comum depois do sucesso e não deve virar exceção na sua aplicação.
• Faça retry com backoff no 503. Espere e tente de novo em vez de repetir na mesma taxa que gerou o bloqueio.
• Não faça retry em 401, 403 e 429. São questões de credencial ou de plano — repetir não resolve.
• Use HEAD para checar a credencial. Valida a API key sem consumir crédito — melhor que gastar uma consulta real só para testar.

Suporte

Dúvidas de integração, limite dedicado ou volume maior: fale com a nossa equipe. Você também pode abrir um chamado direto pelo portal.