Verificación de números

Una verificación de números averigua qué números de teléfono tienen una cuenta de WhatsApp, sin enviarles nada. Limpia una lista antes de una campaña o verifica el número de un registro antes de escribirle. Las verificaciones hechas con la API son las mismas que las listas de la página Verificación de números del panel.

Iniciar una verificación requiere un plan que incluya la verificación de números; si no, la respuesta es 403 plan_required. Leer las verificaciones funciona en cualquier plan.

Iniciar una verificación#

Los números se ponen en cola y la respuesta es 201 con la verificación en estado pending. Un número de WhatsApp conectado de tu espacio de trabajo los verifica en los minutos siguientes. Consulta la verificación hasta que status sea completed y luego lee los 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'];

Respuesta (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 cuántas entradas no eran un número de teléfono (texto, menos de 7 o más de 15 dígitos): no se verifican y no cuentan para tu plan.

Límites del plan#

Tu plan fija cuántos números puedes verificar (consulta Límites del plan):

• Por verificación: una verificación no puede tener más números que el límite del plan. Si lo supera, se rechaza con too_many_numbers, con count y limit.
• Por periodo de facturación: todas las verificaciones juntas, de la API y del panel, tampoco pueden superarlo. Una verificación que lo superaría se rechaza con number_check_quota_reached, con requested, used y limit.
• Un plan sin límite no tiene ninguno de los dos. La API acepta como máximo 10.000 números por solicitud, sea cual sea el plan.
• Una verificación rechazada no pone nada en cola. Divide la lista, espera al siguiente periodo o mejora tu plan.

Errores al iniciar una verificación#

Listar verificaciones#

Las verificaciones del espacio de trabajo, de la más reciente a la más antigua, en páginas (limit de 1 a 100, predeterminado 25, y cursor), incluidas las iniciadas en el panel. Cada una es un Number check.

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

Obtener una verificación#

La verificación y su progreso. Consúltala cada 30 segundos más o menos hasta que status sea 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 verificación que no existe responde 404 number_check_not_found.

La verificación necesita un número de WhatsApp del espacio de trabajo conectado con código QR o código de vinculación, y espera mientras tus números están enviando. Una verificación puede quedarse un rato en pending o processing; consulta Cómo funciona la verificación.

Obtener los resultados#

Los números de la verificación y lo que se encontró, en páginas (limit de 1 a 100, predeterminado 25, y cursor). Puedes leerlos mientras la verificación está en curso: los números que aún no se han verificado están en 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
}

El objeto Number check#

Relacionado#

• Verificación de números en el panel
• Planes y facturación
• Errores