BitBusca › Desenvolvedores › API de telefone
Quem é o dono do número, antes de você responder
Mande o telefone com DDD e receba o titular e o endereço registrado. Útil para conferir lead, qualificar contato e evitar golpe com número trocado.
Hoje: Lead com número de outra pessoa, golpista se passando por cliente, atendente perguntando tudo de novo. Com a API: O número entra; titular e endereço voltam. Você qualifica, confere e atende já sabendo com quem fala.
1 crédito por número · escopo consultas:pessoa · planos a partir de R$ 19,90/mês. Chave de teste grátis.
O que cada número traz
Nem toda linha tem titular ou endereço registrado. Quando não há, a resposta é 404 e não gasta créditos.
Consultar um telefone
curl https://api.bitbusca.net/api/v1/telefone/67900000000 \
-H "Authorization: Bearer $BITBUSCA_API_KEY"{
"tipo": "TELEFONE",
"consulta": "(67) 90000-0000",
"custo": 1,
"dados": {
"titular": "CARLOS EXEMPLO LIMA",
"endereco": {
"logradouro": "RUA DAS FLORES, 123",
"bairro": "CENTRO",
"cidade": "CAMPO GRANDE",
"uf": "MS",
"cep": "79000-000"
}
}
}Exemplo fictício, formato resumido. Referência completa: OpenAPI.
Por que integrar
- Lead qualificado — Descarte contato falso antes de gastar o tempo do vendedor.
- Golpe com número trocado — Compare o titular da linha com o CPF informado no cadastro.
- Atendimento que já sabe quem chama — A ficha abre junto com a ligação ou a conversa.
- Paga só o que encontra — 1 crédito por número. Nada encontrado (404) ou erro do nosso lado não cobra: o débito volta na hora.
Para quem é
- Vendas e marketing — Formulário cheio de número inventado ou de outra pessoa. Saiba se o lead é real antes de passar para o vendedor.
- Atendimento e SAC — O cliente chama e o atendente pergunta nome e endereço de novo. A ficha aparece quando o número chega.
- Antifraude — Cadastro feito com o celular de outra pessoa para receber o código. Titular da linha conferido contra o CPF do cadastro.
O que você recebe
titular— Quem está registrado na linha: confere com quem diz ser.endereco— Onde o titular está registrado: entrega, área de atendimento e conferência.cidade · uf · cep— A região do contato, para mandar ao vendedor ou à loja certa.consulta— O número já formatado, pronto para mostrar na tela.
Telefone também é dado pessoal, e a API trata assim
Finalidade declarada, registro de cada chamada e trava contra varredura: é o que deixa a integração defensável quando alguém pergunta de onde veio o dado.
- Conferência de identidade no cadastro
- Prevenção a golpe e fraude
- Atendimento a quem já é seu cliente
- Qualificação de quem pediu contato
- Conta identificada, com CPF e WhatsApp confirmados, por trás de cada chave
- Detector de varredura: documentos ou números em sequência pausam a chave por 1 hora
- Cada chamada registrada no log da sua conta, sem gravar o dado consultado
- Termos proíbem revenda, redistribuição e base derivada
O que entrega
- Nome do titular
- CPF do titular (quando registrado)
- Endereço: logradouro, bairro, cidade/UF e CEP
Endpoints e custo
GET /v1/telefone/{numero}— Titular do número (DDD + número, só dígitos) (1 crédito)
Limites e proteção
- 1 crédito por consulta; 404 não cobra.
- Detector de varredura: números em sequência pausam a chave por 1 hora (429 ENUMERACAO).
- Uso com finalidade legítima, conforme a LGPD.
Casos de uso
- Qualificação de leads — Descubra se o contato que chegou pelo formulário é quem diz ser.
- Atendimento — Mostre a ficha do cliente quando o número liga.
- Antifraude — Compare o titular da linha com o CPF informado no cadastro.
Prompt para Lovable, Cursor ou Bolt
Crie uma tela de atendimento: ao colar um telefone com DDD, chame GET /v1/telefone/{numero} (só dígitos) e mostre o titular e o endereço num cartão.
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.Perguntas frequentes
Dá para testar sem pagar?
Sim. A chave de teste (bk_test_…) é grátis, não expira com o sandbox e devolve dados fictícios no mesmo formato da produção — dá para montar a tela inteira sem gastar nada. Quando quiser dado real, ative o sandbox: 7 dias com 50 créditos reais, 10 requisições por minuto, 2 chaves e 1 webhook, uma vez por conta.
Pago por chamada que não encontra nada?
Não. Resposta 404 (nada encontrado) e erro do nosso lado (5xx) não gastam créditos: o débito é estornado na hora.
Em que formato mando o número?
Só dígitos, com DDD: 67900000000. Sem +55.
Posso consultar o telefone de qualquer pessoa?
A consulta precisa de finalidade legítima: conferir um cadastro, prevenir fraude, atender quem já é cliente. Montar lista para revender ou varrer números em sequência é proibido nos termos e pausa a chave.
Tem limite de consultas por dia?
O limite é o pool mensal de créditos do plano (1 crédito por número) e as requisições por minuto de cada plano. Você ainda pode pôr um teto diário de créditos em cada chave. O que pausa a chave é varredura: documentos em sequência ou volume fora do padrão.
Outras APIs
- API de CPF — Cadastro da pessoa física a partir do CPF, em JSON. (1 crédito por CPF)
- API de busca por nome — Pessoas encontradas pelo nome, com dados para separar homônimos. (1 crédito por busca)
- API de placa — Dados do veículo pela placa ou pelo número do motor. (5 créditos por placa)
- API de CNPJ — Ficha da empresa com quadro de sócios, pelo CNPJ. (1 crédito por CNPJ)
- API de empresas (leads B2B) — Empresas por CNAE, cidade, porte e abertura — leads B2B. (1 crédito por página)
- API de leads de pessoas — Contatos por região, sem CPF e sem repetição, a partir do Scale. (1 crédito a cada 10 contatos, a partir do Scale)
- API de advogados (OAB) — Ficha do advogado pela OAB e busca por nome. (1 crédito por ficha)
- API do DJEN (publicações e prazos) — Publicações por OAB, parte ou processo, monitores e prazos. (1 crédito por página de busca)
- API de licitações (editais abertos) — Editais abertos, itens, análise por IA e alertas. (1 crédito por página)
- API de imóveis (cadastro municipal) — Ficha do lote do cadastro da prefeitura — 7 cidades. (5 créditos por ficha, a partir do Builder)
- Servidor MCP (conector para IAs) — Conector para Claude, ChatGPT, Cursor e outras IAs. (O custo de cada ferramenta é o da rota)
- Webhooks — Eventos assinados com HMAC: intimação, edital, empresa nova. (Sem custo por entrega)