Verifiche dei numeri

Una verifica dei numeri scopre quali numeri di telefono hanno un account WhatsApp, senza inviare loro nulla. Pulisci un elenco prima di una campagna, o verifica il numero di un nuovo iscritto prima di scrivergli. Le verifiche fatte con l'API sono le stesse degli elenchi nella pagina Verifica dei numeri della dashboard.

Per avviare una verifica serve un piano che includa la verifica dei numeri; altrimenti la richiesta risponde 403 plan_required. Leggere le verifiche funziona con qualsiasi piano.

Avviare una verifica#

I numeri vengono messi in coda e la risposta è 201 con la verifica in stato pending. Un numero WhatsApp collegato del tuo spazio di lavoro li verifica nei minuti successivi. Interroga la verifica finché status non è completed, poi leggi i risultati.

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'];

Risposta (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 indica quante voci non erano un numero di telefono (testo, meno di 7 o più di 15 cifre): non vengono verificate e non contano per il tuo piano.

Limiti del piano#

Il tuo piano stabilisce quanti numeri puoi verificare (vedi Limiti del piano):

• Per verifica: una verifica non può avere più numeri di quanti ne preveda il piano. Oltre questo valore, la verifica viene rifiutata con too_many_numbers, con count e limit.
• Per periodo di fatturazione: anche tutte le verifiche insieme, dall'API e dalla dashboard, non possono superarlo. Una verifica che lo supererebbe viene rifiutata con number_check_quota_reached, con requested, used e limit.
• Un piano senza limite non ha né l'uno né l'altro. Qualunque sia il piano, l'API accetta al massimo 10.000 numeri per richiesta.
• Una verifica rifiutata non mette in coda nulla. Dividi l'elenco, attendi il periodo successivo o passa a un piano superiore.

Errori all'avvio di una verifica#

Elencare le verifiche#

Le verifiche dello spazio di lavoro, dalla più recente, in pagine (limit da 1 a 100, predefinito 25, e cursor), comprese quelle avviate nella dashboard. Ognuna è un Number check.

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

Ottenere una verifica#

La verifica e il suo avanzamento. Interrogala circa ogni 30 secondi finché status non è 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"
}

Una verifica che non esiste risponde 404 number_check_not_found.

Per verificare serve un numero WhatsApp dello spazio di lavoro collegato con codice QR o codice di abbinamento, e la verifica attende mentre i tuoi numeri stanno inviando. Una verifica può restare pending o processing per un po'; vedi Come funziona la verifica.

Ottenere i risultati#

I numeri della verifica e cosa è stato trovato, in pagine (limit da 1 a 100, predefinito 25, e cursor). Puoi leggerli mentre la verifica è in corso: i numeri non ancora verificati sono 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
}

L'oggetto Number check#

Pagine correlate#

• Verifica dei numeri nella dashboard
• Piani e fatturazione
• Errori