API de consulta de telefone (busca reversa)
O endpoint de telefone faz busca reversa: a partir de um número (fixo ou celular, com DDD) retorna a identificação e os dados cadastrais vinculados, quando disponíveis. É usado em recuperação de crédito, contato de cobrança autorizado e prevenção à fraude.
Para que serve
- Recuperação de crédito: localizar contato atualizado do titular.
- Antifraude: confirmar se o telefone informado bate com o cadastro.
- Validação de contato em fluxos de cobrança autorizados.
Requisição
Autentique com o header Authorization: Bearer — gere seu token no dashboard após ativar um plano.
curl -X POST "https://apiconsultas.xyz/api/v1/consultas/telefone" \
-H "Authorization: Bearer dp_live_xxxxxxxxxxxxxxxxx" \
-H "Content-Type: application/json" \
-d '{"telefone":"11987654321"}'const res = await fetch("https://apiconsultas.xyz/api/v1/consultas/telefone", {
method: "POST",
headers: {
Authorization: "Bearer dp_live_xxxxxxxxxxxxxxxxx",
"Content-Type": "application/json",
},
body: JSON.stringify({"telefone":"11987654321"}),
});
const data = await res.json();<?php
$ch = curl_init("https://apiconsultas.xyz/api/v1/consultas/telefone");
curl_setopt_array($ch, [
CURLOPT_RETURNTRANSFER => true,
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => [
"Authorization: Bearer dp_live_xxxxxxxxxxxxxxxxx",
"Content-Type: application/json",
],
CURLOPT_POSTFIELDS => '{"telefone":"11987654321"}',
]);
$data = json_decode(curl_exec($ch), true);Resposta (200)
Exemplo com valores ilustrativos. O nível de detalhe (dados completos ou mascarados) depende do seu plano.
{
"success": true,
"tipo_consulta": "telefone",
"query": {
"termo_mascarado": "*******4321",
"finalidade": "recuperacao_credito"
},
"resultado_count": 1,
"data_quality": {
"sources_used": 2,
"confidence_score": 85,
"has_contacts": true,
"has_address": true
},
"data": [
{
"identificacao": {
"nome": "NOME DO TITULAR",
"documento": "123.***.**9-09"
},
"contato": {
"telefones": [
"(11) 98765-4321"
],
"emails": []
},
"localizacao": {
"cidade": "São Paulo",
"estado": "SP"
}
}
],
"audit": {
"logged": true,
"timestamp": "2026-07-01T12:00:00.000Z"
},
"message": "Consulta realizada com sucesso."
}Campos retornados
| Campo | Descrição |
|---|---|
| identificacao.nome | Titular vinculado ao número, quando disponível. |
| contato.telefones_detalhados | Números com metadados (quando disponível). |
| identificacao.documento | Documento do titular (mascarado conforme plano). |
| localizacao | Cidade/UF associadas, quando disponíveis. |
| data_quality | sources_used e confidence_score do resultado. |
Perguntas frequentes
Aceita número fixo e celular?
Sim. Informe o número com DDD (10 ou 11 dígitos). Números com menos de 10 dígitos são rejeitados com erro 400.
Sempre encontra o titular?
Não. A cobertura depende dos dados disponíveis para aquele número. Quando não há registro, a resposta retorna resultado_count 0 — sem cobrar por dado inexistente.
Posso usar para marketing?
Não. O uso é restrito a finalidades legítimas (antifraude, recuperação de crédito, validação), com auditoria por requisição e em conformidade com a LGPD.
Endpoints relacionados
Integre consulta de telefone hoje
Ative um plano a partir de R$ 10, gere seu token Bearer e comece a consultar em minutos. Consultas ilimitadas enquanto o plano estiver ativo.