Referencia

WA Lookup Referencia de la API

Todos los endpoints comparten una clave API y un saldo.

Elemento	Valor
URL base	https://walookup.com
Cabecera de autenticación	X-API-Key: sk_your_api_key
Estructura de la respuesta	{ code, msg, data }

Los precios no se indican aquí; cada producto se factura por verificación correcta. Ver precios

Autenticación

Use una clave API creada en Configuración y envíela con cada solicitud en la cabecera X-API-Key.

Cabecera de autenticación

X-API-Key: sk_your_api_key

Mantenga su clave API en secretoLlame siempre a este endpoint desde su servidor. Cualquiera que tenga la clave puede gastar su saldo.

Verificaciones síncronas

POST/api/v1/checkPOST/api/v1/batch-check

Envíe un identificador, o hasta 100 en una sola solicitud, y lea el resultado en la misma respuesta. Sin sondeo ni callbacks. Un resultado indeterminado devuelve 422 con el código 42200 y no se cobra. Una solicitud múltiple conserva el orden de entrada, factura cada identificador de forma independiente y dispone de 300 segundos para finalizar; si no lo consigue, toda la solicitud falla y se reembolsan todos los cargos.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto, uno de los productos indicados a continuación.
`identifier`	string	Verificación individual: un número de teléfono en formato E.164, con o sin el `+` inicial. El servidor lo normaliza.
`identifiers`	string[]	Verificación múltiple: de 1 a 100 números de teléfono. La respuesta conserva este orden.

Productos de este grupo

Verificación de registro en WhatsAppwsConfirme si un número está registrado en WhatsApp: útil para revisar una lista de contactos antes de enviar mensajes.Página del producto
Verificación de avatar de WhatsAppws_avatarCompruebe si un número está registrado en WhatsApp y obtenga los campos de avatar: avatar (si se obtuvo uno) y avatar_url.Página del producto
Verificación de cuenta de WhatsApp Businessws_businessVerifique el registro e identifique si el número usa una cuenta de WhatsApp Business.Página del producto

Verificación de registro en WhatsApp

wsteléfono

Confirme si un número está registrado en WhatsApp: útil para revisar una lista de contactos antes de enviar mensajes.

Verificación individual

POST/api/v1/check

Solicitud

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "identifier": "+17253100591",
    "registered": true
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`registered`	boolean	Si el número está registrado en WhatsApp.

Verificación múltiple

POST/api/v1/batch-check

Solicitud

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`exists`	boolean	Si este número produjo un resultado. false significa que el formato no era válido, que el resultado fue indeterminado o que la verificación falló; cuando es false, no aparece ninguno de los campos siguientes.
`registered`	boolean	Si el número está registrado (`registered`). Solo aparece cuando `exists` es true, con el mismo significado que en la verificación individual.

Verificación de avatar de WhatsApp

ws_avatarteléfono

Compruebe si un número está registrado en WhatsApp y obtenga los campos de avatar: avatar (si se obtuvo uno) y avatar_url.

Verificación individual

POST/api/v1/check

Solicitud

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_avatar", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_avatar",
    "identifier": "+17253100591",
    "registered": true,
    "avatar": true,
    "avatar_url": "<image url>"
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`registered`	boolean	Si el número está registrado en WhatsApp.
`avatar`	boolean	Si la cuenta tiene un avatar configurado. avatar_url puede seguir vacío cuando la imagen no está disponible.
`avatar_url`	string	La URL del avatar; una cadena vacía cuando no hay ninguna URL disponible.

Verificación múltiple

POST/api/v1/batch-check

Solicitud

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_avatar", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_avatar",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "avatar": true,
        "avatar_url": "<image url>"
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "avatar": false,
        "avatar_url": ""
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`exists`	boolean	Si este número produjo un resultado. false significa que el formato no era válido, que el resultado fue indeterminado o que la verificación falló; cuando es false, no aparece ninguno de los campos siguientes.
`registered`	boolean	Si el número está registrado (`registered`). Solo aparece cuando `exists` es true, con el mismo significado que en la verificación individual.
`avatar`	boolean	Si la cuenta tiene un avatar configurado. avatar_url puede seguir vacío cuando la imagen no está disponible.
`avatar_url`	string	La URL del avatar; una cadena vacía cuando no hay ninguna URL disponible.

Verificación de cuenta de WhatsApp Business

ws_businessteléfono

Verifique el registro e identifique si el número usa una cuenta de WhatsApp Business.

Verificación individual

POST/api/v1/check

Solicitud

curl -X POST "https://walookup.com/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_business", "identifier": "+17253100591" }'

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_business",
    "identifier": "+17253100591",
    "registered": true,
    "business": true
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`registered`	boolean	Si el número está registrado en WhatsApp.
`business`	boolean	Si la cuenta es una cuenta de WhatsApp Business.

Verificación múltiple

POST/api/v1/batch-check

Solicitud

curl -X POST "https://walookup.com/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "ws_business", "identifiers": ["+17253100591", "+14155550000", "12345"] }'

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "ws_business",
    "total": 3,
    "succeeded": 2,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "registered": true,
        "business": true
      },
      {
        "identifier": "+14155550000",
        "exists": true,
        "registered": false,
        "business": false
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}

Campos de la respuesta

Campo	Tipo	Descripción
`exists`	boolean	Si este número produjo un resultado. false significa que el formato no era válido, que el resultado fue indeterminado o que la verificación falló; cuando es false, no aparece ninguno de los campos siguientes.
`registered`	boolean	Si el número está registrado (`registered`). Solo aparece cuando `exists` es true, con el mismo significado que en la verificación individual.
`business`	boolean	Si la cuenta es una cuenta de WhatsApp Business.

Verificaciones asíncronas

POST/api/v1/bulk-tasksGET/api/v1/bulk-tasks/{id}

Suba un archivo y obtenga al instante un ID de tarea; después, consulte ese ID hasta que se complete correctamente. La respuesta correcta incluye result_url, el enlace de descarga del resultado. Solo existen dos acciones: enviar y consultar. No sondee más de una vez cada 30 segundos.

Parámetros

Campo	Tipo	Descripción
`service_type`	string	Código de producto masivo, uno de los productos indicados a continuación.
`country`	string	Código ISO 3166-1, como `US`. Obligatorio para las tareas de números: cada número debe incluir su código de país y pertenecer a este país (los que no lo cumplan se excluyen y no se cobran); también selecciona el enrutamiento. En multipart debe ir antes de `file`.
`file`	file	Un archivo `.txt` o `.csv` con un identificador por línea, de hasta `max_file_bytes` (20MB por defecto).
`Idempotency-Key`	header	Opcional, hasta 128 caracteres. Repetir la misma clave devuelve la tarea original en lugar de crear una segunda.

Productos de este grupo

Verificación masiva de registro en WhatsAppws_batchSuba un archivo completo de números, averigüe cuáles están registrados en WhatsApp y descargue el archivo de resultados cuando termine.Página del producto
Verificación masiva de avatar de WhatsAppws_avatar_batchVerifique en toda una lista el registro en WhatsApp y el avatar: si cada número registrado tiene un avatar configurado, además de la URL del avatar.Página del producto
Verificación masiva Business de WhatsAppws_business_batchVerifique en toda una lista las cuentas de WhatsApp Business: si cada número está en WhatsApp y si esa cuenta es una cuenta de WhatsApp Business.Página del producto
Verificación masiva de actividad en WhatsAppws_active_batchEstado de registro más días de actividad (días desde la última actividad del número), para distinguir los números vivos de los inactivos en toda una lista.Página del producto

Verificación masiva de registro en WhatsApp

ws_batchteléfono1000–500.000 por tarea

Suba un archivo completo de números, averigüe cuáles están registrados en WhatsApp y descargue el archivo de resultados cuando termine.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`activated`	true	Si el número está registrado en WhatsApp: true o false.

Verificación masiva de avatar de WhatsApp

ws_avatar_batchteléfono1000–500.000 por tarea

Verifique en toda una lista el registro en WhatsApp y el avatar: si cada número registrado tiene un avatar configurado, además de la URL del avatar.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_avatar_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_avatar_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_avatar_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`activated`	true	Si el número está registrado en WhatsApp: true o false. Cuando no es true, todas las demás columnas de esa fila se dejan vacías.
`avatar`	true	Si la cuenta tiene un avatar configurado: true o false. avatar_url puede seguir vacío cuando la imagen no está disponible.
`avatar_url`	https://pps.whatsapp.net/v/example.jpg	La URL del avatar; vacía cuando no hay ninguna URL disponible.

Verificación masiva Business de WhatsApp

ws_business_batchteléfono1000–500.000 por tarea

Verifique en toda una lista las cuentas de WhatsApp Business: si cada número está en WhatsApp y si esa cuenta es una cuenta de WhatsApp Business.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_business_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_business_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_business_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`activated`	true	Si el número está registrado en WhatsApp: true o false. Cuando no es true, todas las demás columnas de esa fila se dejan vacías.
`business`	false	Si la cuenta es una cuenta de WhatsApp Business: true o false.

Verificación masiva de actividad en WhatsApp

ws_active_batchteléfono1000–500.000 por tarea

Estado de registro más días de actividad (días desde la última actividad del número), para distinguir los números vivos de los inactivos en toda una lista.

Enviar una tarea

POST/api/v1/bulk-tasks

Solicitud

curl -X POST "https://walookup.com/api/v1/bulk-tasks" \
  -H "X-API-Key: sk_your_api_key" \
  -F service_type=ws_active_batch \
  -F country=US \
  -F file=@numbers.txt

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_active_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1015,
    "invalid_cnt": 0,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 0,
    "preparing": true,
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Consultar la tarea

GET/api/v1/bulk-tasks/{id}

Solicitud

curl "https://walookup.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "ws_active_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 1015,
    "total": 1000,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 12,
    "preparing": false,
    "success_cnt": 990,
    "failure_cnt": 10,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

Columnas del resultado

Campo	ejemplo:	Descripción
`identifier`	17253100591	El número enviado como dígitos sin formato con el código de país, sin signo más ni espacios (p. ej., 17253100591).
`activated`	true	Si el número está registrado en WhatsApp: true o false. Cuando no es true, todas las demás columnas de esa fila se dejan vacías.
`activedays`	9	Días desde la última actividad del número: cuanto menor, más reciente.

Saldo

GET/api/v1/balance

Consulte el saldo actual de la cuenta en micros de USD. Solo lectura: no crea ningún registro de verificación ni cobra nada.

Saldo

GET/api/v1/balance

Solicitud

curl "https://walookup.com/api/v1/balance" \
  -H "X-API-Key: sk_your_api_key"

Respuesta

{
  "code": 0,
  "msg": "ok",
  "data": {
    "balance_micros": 12500000
  }
}

Concurrencia, tiempos de espera y comportamiento de reintento

Las verificaciones son síncronas. Use el código devuelto para decidir si acepta el resultado o reintenta.

Campo	Descripción
`5 solicitudes simultáneas por usuario`	Las verificaciones individuales y múltiples comparten este límite, y una solicitud múltiple cuenta como una sola solicitud, independientemente de cuántos números incluya. Además, solo se ejecuta una verificación múltiple por cuenta a la vez; una segunda se rechaza hasta que termine la primera. Alcanzar cualquiera de los dos límites devuelve de inmediato el `code` `42901` sin cargo, junto con una cabecera `Retry-After`: vuelva a enviar la solicitud cuando termine una solicitud en curso.
`60 s individual, 300 s múltiple`	Superar el tiempo límite devuelve el `code` `50400` sin cargo. Una verificación múltiple que supera el tiempo de espera falla en su totalidad: no hay resultados parciales y se reembolsa el importe completo.
`Una verificación múltiple admite hasta 100 números`	Los resultados conservan el orden y la longitud del envío. Solo se ejecuta una verificación múltiple por cuenta a la vez; envíe el siguiente lote cuando el anterior haya devuelto sus resultados.

Códigos de error

Código	Descripción
`40000`	Tipo de servicio no compatible o campos de la solicitud en conflicto
`40001`	Cuerpo JSON no válido
`40002`	Número no válido
`40100`	Clave API ausente o no válida
`40200`	Saldo insuficiente
`42200`	No se ha podido determinar el número en este momento. No se devuelve `data` y la solicitud no se cobra
`42900`	Se ha agotado una cuota de uso o hay demasiados pedidos sin finalizar
`42901`	Las cinco plazas de solicitudes simultáneas están ocupadas o ya hay una verificación múltiple en ejecución en esta cuenta; envíe la solicitud cuando termine una solicitud en curso. La solicitud rechazada no se cobra e incluye una cabecera `Retry-After`
`50303`	El servicio está a plena capacidad en este momento; no se cobra. Espere los segundos indicados en `Retry-After` y vuelva a enviar la misma solicitud
`50400`	La verificación no finalizó dentro de su tiempo de espera y no se cobra; reinténtela. Si se agota el tiempo de un lote, falla el lote completo y se reembolsa el importe total
`50300`	Mantenimiento del servicio de validación