API de verificação de números
Resultados da verificação de números de WhatsApp (API)
Leia os resultados da verificação de números página por página, filtrando por tarefa ou por status. Use-a para exportar os números que têm WhatsApp, remover números inválidos da sua lista de contatos ou sincronizar os resultados com o seu CRM.
https://wbiztool.com/api/v1/verification/results/Sem filtros, ela retorna todas as verificações do seu espaço de trabalho, das mais recentes para as mais antigas. Isso inclui tarefas criadas pela página Verificação de Número do painel, e não só as criadas pela API.
Exemplo rápido#
curl "https://wbiztool.com/api/v1/verification/results/?campaign_id=4521&status=verified&limit=100&offset=0" \
-H "Authorization: Bearer YOUR_API_KEY"import requests
response = requests.get(
"https://wbiztool.com/api/v1/verification/results/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"campaign_id": 4521, "status": "verified", "limit": 100, "offset": 0},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 4xx or 5xx
if result["status"] == "success":
print(f"{result['returned_count']} of {result['total_count']} results")
for item in result["results"]:
print(item["number"], item["status"])
else:
print(f"Failed ({response.status_code}):", result["message"])// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const url = new URL("https://wbiztool.com/api/v1/verification/results/");
url.search = new URLSearchParams({ campaign_id: "4521", status: "verified", limit: "100", offset: "0" });
const response = await fetch(url, {
headers: { Authorization: "Bearer YOUR_API_KEY" },
});
const result = await response.json(); // read the body even when the HTTP code is 4xx or 5xx
if (result.status === "success") {
console.log(`${result.returned_count} of ${result.total_count} results`);
for (const item of result.results) {
console.log(item.number, item.status);
}
} else {
console.error(`Failed (${response.status}):`, result.message);
}<?php
$query = http_build_query([
'campaign_id' => 4521,
'status' => 'verified',
'limit' => 100,
'offset' => 0,
]);
$ch = curl_init('https://wbiztool.com/api/v1/verification/results/?' . $query);
curl_setopt_array($ch, [
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY'],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? '') === 'success') {
echo $result['returned_count'] . ' of ' . $result['total_count'] . " results\n";
foreach ($result['results'] as $item) {
echo $item['number'] . ': ' . $item['status'] . "\n";
}
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}Parâmetros da requisição#
Todos os parâmetros vão na query string.
Autenticação
AuthorizationheaderobrigatórioBearer YOUR_API_KEY, usando uma chave de Configurações → Chaves API. Você também pode passar a chave como parâmetro de queryapi_key, mas o cabeçalho a mantém fora dos logs do servidor e de proxies.
Filtros e paginação
campaign_idintegeropcionalRetorna somente os números desta tarefa de verificação. Precisa ser uma tarefa de verificação do mesmo espaço de trabalho da chave de API. Não envie para obter os resultados de todas as tarefas.
statusstringopcionalRetorna somente os números com este status:
pending,verifiedouinvalid. Qualquer outro valor é ignorado e nenhum filtro de status é aplicado, inclusiveunknown, entãostatus=unknownretorna todos os status. Os valores diferenciam maiúsculas de minúsculas:Verifiedé ignorado e retorna todos os status.limitintegeropcionalResultados por página. Padrão
100. Use um valor igual ou maior que 1.offsetintegeropcionalQuantos resultados pular. Padrão
0. Precisa ser igual ou maior que 0.
Resposta#
Uma requisição bem-sucedida retorna HTTP 200:
{
"status": "success",
"total_count": 2,
"returned_count": 2,
"limit": 100,
"offset": 0,
"has_more": false,
"results": [
{
"id": 88215,
"campaign_id": 4521,
"campaign_name": "Website leads - September",
"number": "14155550123",
"status": "verified",
"checked_at": "2026-09-16T10:16:26.730114+00:00",
"created_at": "2026-09-16T10:15:00.483101+00:00"
},
{
"id": 88213,
"campaign_id": 4521,
"campaign_name": "Website leads - September",
"number": "919876543210",
"status": "verified",
"checked_at": "2026-09-16T10:16:12.204551+00:00",
"created_at": "2026-09-16T10:15:00.482913+00:00"
}
]
}
| Campo | Tipo | Descrição |
|---|---|---|
status | string | "success". Os erros retornam "error". |
total_count | integer | Resultados que correspondem aos seus filtros, somando todas as páginas. |
returned_count | integer | Resultados nesta resposta. |
limit | integer | O limit usado. |
offset | integer | O offset usado. |
has_more | boolean | true se offset + limit for menor que total_count, ou seja, se há outra página. |
results | array | Os resultados, dos mais recentes para os mais antigos. |
results[].id | integer | ID deste registro de verificação. |
results[].campaign_id | integer ou null | ID da tarefa à qual o número pertence. |
results[].campaign_name | string ou null | Nome dessa tarefa. |
results[].number | string | O número de telefone limpo. |
results[].status | string | pending, verified, invalid, ou unknown para uma verificação cancelada. |
results[].checked_at | string ou null | Quando o número foi verificado, ou null enquanto estiver pendente. |
results[].created_at | string | Quando o número foi adicionado. |
Os timestamps estão em ISO 8601, em UTC, com deslocamento +00:00. Para saber o que cada status significa, veja Valores de status do número.
Erros#
Os erros retornam um corpo JSON com status igual a "error" e um código de erro HTTP:
{ "status": "error", "message": "Campaign not found" }
| HTTP | Mensagem | Como corrigir |
|---|---|---|
405 | Only GET method allowed | Envie uma requisição GET. |
401 | API key required | Adicione o cabeçalho Authorization: Bearer YOUR_API_KEY. |
401 | Invalid API key | Verifique se a chave existe e não foi excluída nem desativada. |
404 | Campaign not found | O campaign_id não existe, não é uma tarefa de verificação ou pertence a outro espaço de trabalho. |
500 | Internal server error: … | Geralmente campaign_id, limit ou offset não é um número inteiro, offset é negativo ou offset + limit é negativo. |
Ler todas as páginas#
Aumente offset em limit até que has_more seja false.
import requests
numbers, offset, limit = [], 0, 500
while True:
response = requests.get(
"https://wbiztool.com/api/v1/verification/results/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
params={"campaign_id": 4521, "status": "verified", "limit": limit, "offset": offset},
timeout=60,
)
result = response.json()
if result["status"] != "success":
raise RuntimeError(result["message"])
numbers += [item["number"] for item in result["results"]]
if not result["has_more"]:
break
offset += limit
print(len(numbers), "numbers are on WhatsApp")// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const numbers = [];
const limit = 500;
let offset = 0;
while (true) {
const url = new URL("https://wbiztool.com/api/v1/verification/results/");
url.search = new URLSearchParams({ campaign_id: "4521", status: "verified", limit: String(limit), offset: String(offset) });
const response = await fetch(url, { headers: { Authorization: "Bearer YOUR_API_KEY" } });
const result = await response.json();
if (result.status !== "success") throw new Error(result.message);
numbers.push(...result.results.map((item) => item.number));
if (!result.has_more) break;
offset += limit;
}
console.log(numbers.length, "numbers are on WhatsApp");Dicas#
- Remova duplicados por
idao paginar. Os resultados são ordenados pela data de criação, dos mais recentes para os mais antigos. Números da mesma tarefa têm quase o mesmo timestamp e novas verificações podem ser adicionadas enquanto você pagina, então uma linha pode aparecer em duas páginas ou ser pulada. Filtrar porcampaign_ide esperar a tarefa terminar reduz esse problema. - Aguarde a conclusão antes de exportar. Consulte Status da verificação até que
overall_statussejacompleted, ou trate os resultadospendingno seu código. - Limpe sua lista de contatos exportando
status=invalide removendo esses números antes da sua próxima campanha. - Tamanho da página: não há
limitmáximo, mas uma página muito grande gera uma resposta grande e lenta.
