BitBusca › Desenvolvedores › API de leads de pessoas
Contatos de pessoas por região para campanhas, entregues com as travas que a LGPD pede: sem CPF, um canal por geração (telefone ou e-mail), o mesmo contato nunca duas vezes para você e cada entrega registrada.
Hoje: Lista de contatos de origem duvidosa, com CPF exposto e gente repetida: risco de LGPD em cada envio. Com a API: Contatos por bairro ou cidade, um canal por vez, nunca repetidos para você, sem CPF e com cada entrega registrada.
1 crédito a cada 10 contatos · escopo pessoas:leads · a partir do Scale · planos a partir de R$ 19,90/mês. Chave de teste grátis.
curl -X POST https://api.bitbusca.net/api/v1/pessoas/leads \
-H "Authorization: Bearer $BITBUSCA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"uf":"MS","municipio":"CAMPO GRANDE","bairro":"CENTRO","canal":"telefone","quantidade":50}'{
"entregues": 50,
"custo": 5,
"items": [
{ "id": "lead_7f3a…", "nome": "JOSE EXEMPLO", "telefone": "(67) 90000-0000" }
]
}Exemplo fictício, formato resumido. Referência completa: OpenAPI.
id — Identificador lead_…: evita contatar a mesma pessoa duas vezes sem guardar CPF.nome — Para personalizar a mensagem.telefone ou email — Um canal por geração, o que você escolher.entregues · custo — Quantos contatos vieram e quantos créditos saíram.Começa no plano Scale porque dado de pessoa em lista pede conta madura e uso declarado. Os tetos são o argumento que você leva ao seu jurídico: menos dado, rastreável, sem CPF.
POST /v1/pessoas/leads/contagem — Quantos contatos o recorte tem (antes de gerar)POST /v1/pessoas/leads — Gera até 100 contatos por chamada (1 crédito a cada 10 contatos)Crie uma tela de campanha local: o usuário escolhe UF, cidade e bairro e o canal (telefone ou e-mail). Primeiro chame POST /v1/pessoas/leads/contagem para mostrar quantos contatos existem; depois, ao confirmar, POST /v1/pessoas/leads com a quantidade (até 100) e liste os contatos.
Use a API da BitBusca (base https://api.bitbusca.net/api). A especificação OpenAPI está em https://api.bitbusca.net/api/v1/openapi.json.
Autentique com o cabeçalho "Authorization: Bearer <chave>", lendo a chave da variável de ambiente BITBUSCA_API_KEY.
Nunca coloque a chave no código do navegador: faça as chamadas por uma função de servidor (edge function, API route ou backend).
Trate os erros pelo campo "code" da resposta: 402 NO_CREDITS (sem créditos), 429 RATE (respeite o cabeçalho Retry-After), 429 COTA_DIARIA (teto do dia atingido), 404 NOT_FOUND (mostre "nada encontrado", não é cobrado).
Comece com a chave de teste (bk_test_…), que devolve dados fictícios e não gasta créditos.Porque lead para campanha não precisa de CPF, e não entregar o documento reduz o risco para você e para as pessoas. O id lead_… é estável na sua conta, o que basta para não contatar a mesma pessoa duas vezes.
É a mesma regra do Radar de Pessoas do painel: menos dado pessoal por entrega, mesma eficácia para campanha.
Siga as regras do canal que você usa e a LGPD (base legal, opção de sair). Disparo que gere denúncia é responsabilidade de quem envia.
Você precisa de base legal para a campanha e de oferecer a opção de não receber mais mensagens. A API ajuda reduzindo o dado entregue (sem CPF, um canal por vez) e registrando cada entrega; a decisão sobre a base legal é de quem envia.
Depende do plano: não incluso no Starter, não incluso no Builder, 500 no Scale e 1.000 no Enterprise. Cada chamada gera até 100 contatos e custa 1 crédito a cada 10.