API de verificación de números
Resultados de la verificación de números de WhatsApp (API)
Lee los resultados de la verificación de números página a página, filtrados por tarea o por estado. Úsala para exportar los números que están en WhatsApp, quitar los números no válidos de tu lista de contactos o sincronizar los resultados con tu CRM.
https://wbiztool.com/api/v1/verification/results/Sin filtros, devuelve todas las verificaciones de tu espacio de trabajo, de la más reciente a la más antigua. Eso incluye las tareas creadas desde la página Verificación de Números del panel, no solo las creadas a través de la API.
Ejemplo 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 de la solicitud#
Todos los parámetros van en la query string.
Autenticación
AuthorizationheaderobligatorioBearer YOUR_API_KEY, con una clave de Configuración → Claves API. También puedes pasar la clave como parámetro de consultaapi_key, pero la cabecera evita que quede en los registros del servidor y de los proxies.
Filtros y paginación
campaign_idintegeropcionalDevuelve solo los números de esta tarea de verificación. Debe ser una tarea de verificación del mismo espacio de trabajo que la clave API. Omítelo para obtener los resultados de todas las tareas.
statusstringopcionalDevuelve solo los números con este estado:
pending,verifiedoinvalid. Cualquier otro valor se ignora y no se aplica ningún filtro de estado, incluidounknown, así questatus=unknowndevuelve todos los estados. Los valores distinguen mayúsculas y minúsculas:Verifiedse ignora y devuelve todos los estados.limitintegeropcionalResultados por página. Valor predeterminado:
100. Usa un valor de 1 o más.offsetintegeropcionalCuántos resultados se omiten. Valor predeterminado:
0. Debe ser 0 o más.
Respuesta#
Una solicitud correcta devuelve 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 | Descripción |
|---|---|---|
status | string | "success". Los errores devuelven "error". |
total_count | integer | Resultados que coinciden con tus filtros, en todas las páginas. |
returned_count | integer | Resultados de esta respuesta. |
limit | integer | El limit utilizado. |
offset | integer | El offset utilizado. |
has_more | boolean | true si offset + limit es menor que total_count, es decir, si hay otra página. |
results | array | Los resultados, del más reciente al más antiguo. |
results[].id | integer | ID de este registro de verificación. |
results[].campaign_id | integer or null | ID de la tarea a la que pertenece el número. |
results[].campaign_name | string or null | Nombre de esa tarea. |
results[].number | string | El número de teléfono limpio. |
results[].status | string | pending, verified, invalid o unknown para una comprobación cancelada. |
results[].checked_at | string or null | Cuándo se comprobó el número, o null mientras está pendiente. |
results[].created_at | string | Cuándo se añadió el número. |
Las marcas de tiempo están en ISO 8601 en UTC, con un desfase +00:00. Para saber qué significa cada estado, consulta Valores de estado del número.
Errores#
Los errores devuelven un cuerpo JSON con status con valor "error" y un código de error HTTP:
{ "status": "error", "message": "Campaign not found" }
| HTTP | Mensaje | Cómo solucionarlo |
|---|---|---|
405 | Only GET method allowed | Envía una solicitud GET. |
401 | API key required | Añade la cabecera Authorization: Bearer YOUR_API_KEY. |
401 | Invalid API key | Comprueba que la clave existe y que no se ha eliminado ni desactivado. |
404 | Campaign not found | El campaign_id no existe, no es una tarea de verificación o pertenece a otro espacio de trabajo. |
500 | Internal server error: … | Normalmente campaign_id, limit u offset no es un número entero, offset es negativo, o offset + limit es negativo. |
Leer todas las páginas#
Aumenta offset en limit hasta que has_more sea 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");Consejos#
- Elimina duplicados por
idal paginar. Los resultados se ordenan por fecha de creación, del más reciente al más antiguo. Los números de una misma tarea tienen casi la misma marca de tiempo y se pueden añadir nuevas verificaciones mientras paginas, así que una fila puede aparecer en dos páginas u omitirse. Filtrar porcampaign_idy esperar a que la tarea termine lo reduce. - Espera a que termine antes de exportar. Consulta Estado de la verificación hasta que
overall_statusseacompleted, o gestiona en tu código los resultadospending. - Limpia tu lista de contactos exportando
status=invalidy eliminando esos números antes de tu próxima campaña. - Tamaño de página: no hay un
limitmáximo, pero una página muy grande genera una respuesta grande y lenta.
