Verificação de números

Uma verificação de números descobre quais números de telefone têm uma conta de WhatsApp, sem enviar nada a eles. Limpe uma lista antes de uma campanha ou verifique o número de um cadastro antes de mandar mensagem. As verificações feitas pela API são as mesmas listas da página Verificação de números do painel.

Iniciar uma verificação exige um plano que inclua a verificação de números; caso contrário, a resposta é 403 plan_required. Ler as verificações funciona em qualquer plano.

Iniciar uma verificação#

Os números entram na fila e a resposta é 201 com a verificação no status pending. Um número de WhatsApp conectado do seu espaço de trabalho os verifica nos minutos seguintes. Consulte a verificação periodicamente até que status seja completed e então leia os resultados.

curl -X POST https://wbiztool.com/api/v2/number-checks \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: october-leads" \
  -d '{
    "name": "October leads",
    "numbers": ["+919876543210", "+447700900123", "+14155550123"]
  }'

import os
import time
import requests

API = "https://wbiztool.com/api/v2"
headers = {"Authorization": f"Bearer {os.environ['WBIZTOOL_API_KEY']}"}

check = requests.post(f"{API}/number-checks", headers=headers, timeout=60, json={
    "name": "October leads",
    "numbers": ["+919876543210", "+447700900123", "+14155550123"],
}).json()
print("Skipped entries:", check["skipped"])

while check["status"] != "completed":
    time.sleep(30)
    check = requests.get(f"{API}/number-checks/{check['id']}", headers=headers, timeout=30).json()
    print(check["counts"])

params = {"limit": 100}
while True:
    page = requests.get(f"{API}/number-checks/{check['id']}/results",
                        headers=headers, params=params, timeout=30).json()
    for result in page["data"]:
        print(result["number"], result["status"])
    if not page["next_cursor"]:
        break
    params["cursor"] = page["next_cursor"]

// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const API = "https://wbiztool.com/api/v2";
const headers = { Authorization: `Bearer ${process.env.WBIZTOOL_API_KEY}`, "Content-Type": "application/json" };
const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

let check = await (await fetch(`${API}/number-checks`, {
  method: "POST",
  headers,
  body: JSON.stringify({ name: "October leads", numbers: ["+919876543210", "+447700900123", "+14155550123"] }),
})).json();

while (check.status !== "completed") {
  await sleep(30000);
  check = await (await fetch(`${API}/number-checks/${check.id}`, { headers })).json();
}

const params = new URLSearchParams({ limit: "100" });
while (true) {
  const page = await (await fetch(`${API}/number-checks/${check.id}/results?${params}`, { headers })).json();
  for (const result of page.data) console.log(result.number, result.status);
  if (!page.next_cursor) break;
  params.set("cursor", page.next_cursor);
}

<?php
$ch = curl_init('https://wbiztool.com/api/v2/number-checks');
curl_setopt_array($ch, [
    CURLOPT_POST           => true,
    CURLOPT_HTTPHEADER     => ['Authorization: Bearer ' . getenv('WBIZTOOL_API_KEY'), 'Content-Type: application/json'],
    CURLOPT_POSTFIELDS     => json_encode([
        'name'    => 'October leads',
        'numbers' => ['+919876543210', '+447700900123', '+14155550123'],
    ]),
    CURLOPT_RETURNTRANSFER => true,
]);
$check = json_decode(curl_exec($ch), true);
curl_close($ch);
// Save $check['id'], then poll GET /api/v2/number-checks/{id} until status is completed.
echo $check['id'] . ' ' . $check['status'] . ' skipped: ' . $check['skipped'];

Resposta (201):

{
  "id": 51207,
  "name": "October leads",
  "status": "pending",
  "counts": { "total": 3, "pending": 3, "on_whatsapp": 0, "not_on_whatsapp": 0, "cancelled": 0 },
  "created_at": "2026-10-18T10:40:02.511Z",
  "skipped": 0
}

skipped é quantas entradas não eram um número de telefone (texto, menos de 7 ou mais de 15 dígitos): elas não são verificadas e não contam para o seu plano.

Limites do plano#

O seu plano define quantos números você pode verificar (veja Limites do plano):

• Por verificação: uma verificação não pode ter mais números que o limite do plano. Acima dele, a verificação é recusada com too_many_numbers, com count e limit.
• Por período de cobrança: todas as verificações juntas, da API e do painel, também não podem ultrapassá-lo. Uma verificação que ultrapassaria é recusada com number_check_quota_reached, com requested, used e limit.
• Um plano sem limite não tem nenhum dos dois. A API aceita no máximo 10.000 números por requisição, seja qual for o plano.
• Uma verificação recusada não coloca nada na fila. Divida a lista, espere o próximo período ou faça upgrade.

Erros ao iniciar uma verificação#

Listar verificações#

As verificações do espaço de trabalho, da mais recente para a mais antiga, em páginas (limit de 1 a 100, padrão 25, e cursor), incluindo as iniciadas no painel. Cada uma é um Number check.

curl https://wbiztool.com/api/v2/number-checks \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Obter uma verificação#

A verificação e o progresso dela. Consulte-a a cada 30 segundos, mais ou menos, até que status seja completed.

curl https://wbiztool.com/api/v2/number-checks/51207 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

{
  "id": 51207,
  "name": "October leads",
  "status": "processing",
  "counts": { "total": 3, "pending": 1, "on_whatsapp": 1, "not_on_whatsapp": 1, "cancelled": 0 },
  "created_at": "2026-10-18T10:40:02.511Z"
}

Uma verificação que não existe responde 404 number_check_not_found.

A verificação precisa de um número de WhatsApp do espaço de trabalho conectado por código QR ou código de login, e espera enquanto os seus números estão enviando. Uma verificação pode ficar um tempo em pending ou processing; veja Como a verificação funciona.

Obter os resultados#

Os números da verificação e o que foi encontrado, em páginas (limit de 1 a 100, padrão 25, e cursor). Você pode lê-los enquanto a verificação roda: os números ainda não verificados estão em pending.

curl "https://wbiztool.com/api/v2/number-checks/51207/results?limit=100" \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

{
  "data": [
    { "number": "14155550123", "on_whatsapp": null, "status": "pending", "checked_at": null },
    { "number": "447700900123", "on_whatsapp": false, "status": "not_on_whatsapp", "checked_at": "2026-10-18T10:42:57.204Z" },
    { "number": "919876543210", "on_whatsapp": true, "status": "on_whatsapp", "checked_at": "2026-10-18T10:42:51.880Z" }
  ],
  "next_cursor": null
}

O objeto Number check#

Relacionados#

• Verificação de números no painel
• Planos e cobrança
• Erros