Consulta de Leads (com/sem o 9)
Verifica, antes do disparo, se cada número já existe como lead — exato ou irmão (variante com/sem o nono dígito) — e sinaliza cruzamentos fixo × celular para evitar leads duplicados
Você pode testar esta rota diretamente em nossa documentação interativa.
Rota somente leitura (não cria campanha, não dispara nada, não persiste). Use-a antes das rotas de disparo (externalNotification*) para descobrir se os números que você vai enviar já existem na base — inclusive na variante com/sem o nono dígito — e assim evitar leads duplicados.
No Brasil, um mesmo celular pode estar cadastrado com o 9 (5531988887777) ou sem o 9 (553188887777). A Meta normaliza para uma das formas, então a mesma pessoa pode virar dois leads. Esta rota detecta esses casos e recomenda o número correto a usar.
Boa parte dos casos já é resolvida pelo próprio disparo. Quando o número que você envia não tem lead próprio e a variante com/sem 9 é um celular já validado pela Meta, o disparo reaproveita esse lead sozinho — sem criar duplicata. Esses resultados vêm com autoResolvable: true e não exigem nenhuma ação sua. Use o campo para separar o que é informativo do que realmente precisa de decisão humana.
Tirar ou pôr o “9” pode cruzar a fronteira fixo × celular e ligar duas pessoas diferentes (ex.: um fixo 553135971010 e um celular 5531935971010). Nesses casos (matchType: "cross_number") a rota avisa e nunca recomenda reaproveitar — a decisão é manual.
Endpoint
POST /api/externalAPIs/public/externalLeadSiblingCheck
Parâmetros
Array de objetos com os números a consultar. É a mesma lista que você enviaria ao disparo, para consultar antes sem remontar nada.
Alternativa enxuta ao data: um array de strings de telefone (ex: ["5531988887777", "553188887777"]). Use data ou phones.
País padrão para normalizar números sem DDI. Opcional.
Host alvo. Normalmente resolvido pelo token; informe apenas se usar um token de domínio.
Exemplo
curl -X POST {{BASE_URL}}/api/externalAPIs/public/externalLeadSiblingCheck \
-H "Authorization: Bearer {TOKEN}" \
-H "Content-Type: application/json" \
-d '{
"data": [
{ "phone": "5531988887777" },
{ "phone": "5531935971010" },
{ "phone": "5531999998888" },
{ "phone": "12025550123" }
]
}'
Resposta
{
"code": 200,
"message": "OK",
"data": {
"summary": {
"total": 4,
"withAlerts": 2,
"withoutAlerts": 1,
"autoResolvable": 1,
"skipped": 1
},
"results": [
{
"phone": "5531988887777",
"hasAlert": true,
"autoResolvable": true,
"matchType": "sibling9",
"recommendation": "use_existing",
"recommendedPhone": "553188887777",
"candidates": [
{ "phone": "553188887777", "name": "João Silva", "isExact": false, "validated": true }
],
"description": "Não há lead com este número, mas já existe um lead validado com a variante (com/sem 9) 553188887777. O disparo reaproveita esse lead automaticamente — nenhuma ação é necessária. Se preferir padronizar sua base, use 553188887777."
},
{
"phone": "5531935971010",
"hasAlert": true,
"autoResolvable": false,
"matchType": "cross_number",
"recommendation": "review_manual",
"recommendedPhone": null,
"candidates": [
{ "phone": "553135971010", "name": "Empresa Exemplo Ltda", "isExact": false, "validated": true }
],
"description": "Você enviou o número 5531935971010, mas na base foi encontrado o número 553135971010 (Empresa Exemplo Ltda) — a variante com/sem o 9. Como um é fixo e o outro é celular, podem ser CONTATOS DIFERENTES (pessoas distintas). Revise manualmente antes de disparar; não recomendamos reaproveitar automaticamente."
},
{
"phone": "5531999998888",
"hasAlert": false,
"autoResolvable": false,
"matchType": "none",
"recommendation": null,
"recommendedPhone": null,
"candidates": [],
"description": "Nenhum lead encontrado com este número nem com a variante do 9. Pode disparar normalmente."
}
],
"skipped": [
{
"phone": "12025550123",
"description": "Número inválido ou não é um número BR (fixo ou celular) com DDI 55 — a detecção do 9 não se aplica."
}
]
}
}
Campos da Resposta
Totais da consulta.
Diagnóstico por número avaliado.
Números não avaliáveis (não são celular/fixo BR com DDI 55).
Tipos de correspondência (matchType)
matchType | Alerta | autoResolvable | recommendation | O que significa / o que fazer |
|---|---|---|---|---|
none | não | não | null | Nenhum lead com este número nem com a variante do 9. Pode disparar. |
exact | não | não | null | Já existe um lead exatamente com este número. Sem risco pelo 9. |
sibling9 (irmão validado) | sim | sim | use_existing | Não existe lead com este número, mas existe um celular validado na variante do 9. O disparo reaproveita esse lead sozinho — nenhuma ação necessária. Trocar pelo recommendedPhone é opcional (só padroniza sua base). |
sibling9 (irmão não validado) | sim | não | review_manual | Existe lead na variante do 9, mas sem validação da Meta — o disparo não reaproveita. Revise. |
both_exact_validated | não | não | null | Existem leads nas duas formas; a que você enviou é a validada. Pode disparar. |
both_sibling_validated | sim | não | use_existing | Existem as duas formas; a validada é a variante. Como o número enviado já tem lead, o disparo usa esse lead — use o recommendedPhone se quiser falar com o validado. |
both_none_validated | sim | não | review_manual | Existem leads nas duas formas, nenhum validado. Revise. |
both_validated | sim | não | review_manual | Dois leads validados (com e sem 9) — podem ser 2 contas reais. Revise. |
cross_number | sim | não | review_manual | Cruzamento fixo × celular: as variantes com/sem 9 podem ser pessoas diferentes. Nunca é reaproveitado automaticamente; revise. |
Fluxo sugerido: ignore os resultados com autoResolvable: true — o disparo cuida deles. Dos alertas restantes, para recommendation: "use_existing" troque o telefone pelo recommendedPhone antes de disparar; para review_manual, deixe uma pessoa decidir. Resultados sem alerta seguem para o disparo normalmente.
Erros
| Código | Descrição |
|---|---|
400 | Payload inválido — data (ou phones) ausente/vazio |
401 | Token inválido ou host não resolvido |
500 | Erro interno do servidor |