Справочник

WA Lookup Справочник API

Все эндпоинты используют один ключ API и один баланс.

Параметр	Значение
Базовый URL	https://walookup.com
Заголовок аутентификации	X-API-Key: sk_your_api_key
Обёртка ответа	{ code, msg, data }

Цены здесь не указаны; каждый продукт оплачивается за успешную проверку. Посмотреть цены

Аутентификация

Используйте ключ API, созданный в настройках, и передавайте его в каждом запросе в заголовке X-API-Key.

Заголовок аутентификации

X-API-Key: sk_your_api_key

Храните ключ API в секретеВсегда вызывайте этот эндпоинт со своего сервера. Любой, у кого есть ключ, может расходовать ваш баланс.

Синхронные проверки

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

Отправьте один идентификатор или до 100 в одном запросе и получите результат в том же ответе. Без опроса и обратных вызовов. Неопределённый результат возвращает 422 с кодом 42200 и не оплачивается. Множественный запрос сохраняет порядок ввода, оплачивает каждый идентификатор отдельно и должен завершиться за 300 секунд — иначе весь запрос завершается ошибкой, а все списания возвращаются.

Параметры

Поле	Тип	Описание
`service_type`	string	Код продукта — один из продуктов, перечисленных ниже.
`identifier`	string	Одиночная проверка: один номер телефона в формате E.164, с ведущим `+` или без него. Сервер нормализует его.
`identifiers`	string[]	Множественная проверка: от 1 до 100 номеров телефонов. Ответ сохраняет этот порядок.

Продукты этой группы

Проверка регистрации в WhatsAppwsУзнайте, зарегистрирован ли номер в WhatsApp, — удобно для проверки списка контактов перед отправкой.Страница продукта
Проверка аватара WhatsAppws_avatarПроверьте, зарегистрирован ли номер в WhatsApp, и получите поля аватара: avatar (удалось ли его получить) и avatar_url.Страница продукта
Проверка аккаунта WhatsApp Businessws_businessПроверьте регистрацию и определите, использует ли номер аккаунт WhatsApp Business.Страница продукта

Проверка регистрации в WhatsApp

wsтелефон

Узнайте, зарегистрирован ли номер в WhatsApp, — удобно для проверки списка контактов перед отправкой.

Одиночная проверка

POST/api/v1/check

Запрос

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
  }
}

Поля ответа

Поле	Тип	Описание
`registered`	boolean	Зарегистрирован ли номер в WhatsApp.

Множественная проверка

POST/api/v1/batch-check

Запрос

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"] }'

Ответ

{
  "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
      }
    ]
  }
}

Поля ответа

Поле	Тип	Описание
`exists`	boolean	Получен ли результат по этому номеру. false означает, что формат недопустим, результат не определён или проверка не удалась; при false ни одно из полей ниже не возвращается.
`registered`	boolean	Является ли номер `registered`. Присутствует, только если `exists` равно true; значение то же, что и при одиночной проверке.

Проверка аватара WhatsApp

ws_avatarтелефон

Проверьте, зарегистрирован ли номер в WhatsApp, и получите поля аватара: avatar (удалось ли его получить) и avatar_url.

Одиночная проверка

POST/api/v1/check

Запрос

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>"
  }
}

Поля ответа

Поле	Тип	Описание
`registered`	boolean	Зарегистрирован ли номер в WhatsApp.
`avatar`	boolean	Установлен ли у аккаунта аватар. avatar_url может быть пустым, если изображение недоступно.
`avatar_url`	string	URL аватара; пустая строка, если URL недоступен.

Множественная проверка

POST/api/v1/batch-check

Запрос

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"] }'

Ответ

{
  "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
      }
    ]
  }
}

Поля ответа

Поле	Тип	Описание
`exists`	boolean	Получен ли результат по этому номеру. false означает, что формат недопустим, результат не определён или проверка не удалась; при false ни одно из полей ниже не возвращается.
`registered`	boolean	Является ли номер `registered`. Присутствует, только если `exists` равно true; значение то же, что и при одиночной проверке.
`avatar`	boolean	Установлен ли у аккаунта аватар. avatar_url может быть пустым, если изображение недоступно.
`avatar_url`	string	URL аватара; пустая строка, если URL недоступен.

Проверка аккаунта WhatsApp Business

ws_businessтелефон

Проверьте регистрацию и определите, использует ли номер аккаунт WhatsApp Business.

Одиночная проверка

POST/api/v1/check

Запрос

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
  }
}

Поля ответа

Поле	Тип	Описание
`registered`	boolean	Зарегистрирован ли номер в WhatsApp.
`business`	boolean	Является ли аккаунт аккаунтом WhatsApp Business.

Множественная проверка

POST/api/v1/batch-check

Запрос

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"] }'

Ответ

{
  "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
      }
    ]
  }
}

Поля ответа

Поле	Тип	Описание
`exists`	boolean	Получен ли результат по этому номеру. false означает, что формат недопустим, результат не определён или проверка не удалась; при false ни одно из полей ниже не возвращается.
`registered`	boolean	Является ли номер `registered`. Присутствует, только если `exists` равно true; значение то же, что и при одиночной проверке.
`business`	boolean	Является ли аккаунт аккаунтом WhatsApp Business.

Асинхронные проверки

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

Загрузите файл и сразу получите id задачи, затем проверяйте этот id, пока задача не завершится успешно. Успешный ответ содержит result_url — ссылку для скачивания результата. Действий всего два: отправка и проверка. Опрашивайте не чаще одного раза в 30 секунд.

Параметры

Поле	Тип	Описание
`service_type`	string	Код массового продукта — один из продуктов, перечисленных ниже.
`country`	string	Код ISO 3166-1, например `US`. Обязателен для задач с номерами: каждый номер должен содержать код страны и относиться к этой стране (остальные номера исключаются и не оплачиваются); также определяет маршрутизацию. В multipart должен идти перед `file`.
`file`	file	Файл `.txt` или `.csv` с одним идентификатором на строку, размером до `max_file_bytes` (по умолчанию 20MB).
`Idempotency-Key`	header	Необязательный, до 128 символов. Повторная отправка с тем же ключом возвращает исходную задачу вместо создания новой.

Продукты этой группы

Массовая проверка регистрации в WhatsAppws_batchЗагрузите файл с номерами целиком, узнайте, какие из них зарегистрированы в WhatsApp, и скачайте файл с результатом после завершения.Страница продукта
Массовая проверка аватара WhatsAppws_avatar_batchПроверьте весь список на регистрацию в WhatsApp и аватар: установлен ли аватар у каждого зарегистрированного номера, а также URL аватара.Страница продукта
Массовая проверка Business в WhatsAppws_business_batchПроверьте весь список на аккаунты WhatsApp Business: есть ли каждый номер в WhatsApp и является ли этот аккаунт аккаунтом WhatsApp Business.Страница продукта
Массовая проверка активности в WhatsAppws_active_batchСтатус регистрации плюс дни активности — сколько дней прошло с последней активности номера, — чтобы отличать живые номера от неактивных во всём списке.Страница продукта

Массовая проверка регистрации в WhatsApp

ws_batchтелефон1 000–500 000 на задачу

Загрузите файл с номерами целиком, узнайте, какие из них зарегистрированы в WhatsApp, и скачайте файл с результатом после завершения.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "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"
  }
}

Проверка задачи

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

Запрос

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

Ответ

{
  "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"
  }
}

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в WhatsApp: true или false.

Массовая проверка аватара WhatsApp

ws_avatar_batchтелефон1 000–500 000 на задачу

Проверьте весь список на регистрацию в WhatsApp и аватар: установлен ли аватар у каждого зарегистрированного номера, а также URL аватара.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "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"
  }
}

Проверка задачи

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

Запрос

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

Ответ

{
  "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"
  }
}

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в WhatsApp: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`avatar`	true	Установлен ли у аккаунта аватар: true или false. avatar_url может быть пустым, если изображение недоступно.
`avatar_url`	https://pps.whatsapp.net/v/example.jpg	URL аватара; пусто, если URL недоступен.

Массовая проверка Business в WhatsApp

ws_business_batchтелефон1 000–500 000 на задачу

Проверьте весь список на аккаунты WhatsApp Business: есть ли каждый номер в WhatsApp и является ли этот аккаунт аккаунтом WhatsApp Business.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "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"
  }
}

Проверка задачи

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

Запрос

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

Ответ

{
  "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"
  }
}

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в WhatsApp: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`business`	false	Является ли аккаунт аккаунтом WhatsApp Business: true или false.

Массовая проверка активности в WhatsApp

ws_active_batchтелефон1 000–500 000 на задачу

Статус регистрации плюс дни активности — сколько дней прошло с последней активности номера, — чтобы отличать живые номера от неактивных во всём списке.

Отправка задачи

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "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"
  }
}

Проверка задачи

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

Запрос

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

Ответ

{
  "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"
  }
}

Столбцы результата

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
`activated`	true	Зарегистрирован ли номер в WhatsApp: true или false. Если значение не true, все остальные столбцы в этой строке остаются пустыми.
`activedays`	9	Количество дней с последней активности номера — чем меньше, тем свежее.

Баланс

GET/api/v1/balance

Получение текущего баланса аккаунта в микродолларах USD. Только чтение: запись о проверке не создаётся, списаний нет.

Баланс

GET/api/v1/balance

Запрос

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

Ответ

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

Параллельность, тайм-ауты и повторные попытки

Проверки синхронные. По возвращённому коду решайте, принять результат или повторить попытку.

Поле	Описание
`5 одновременных запросов на пользователя`	Одиночные и множественные проверки делят этот лимит, причём множественный запрос считается одним запросом независимо от количества номеров в нём. Кроме того, для одного аккаунта одновременно выполняется только одна множественная проверка; вторая отклоняется, пока не завершится первая. При достижении любого из лимитов сразу возвращается `code` `42901` без списания и с заголовком `Retry-After` — отправьте запрос повторно, когда завершится один из выполняющихся.
`60 с для одиночной, 300 с для множественной`	При превышении лимита времени возвращается `code` `50400` без списания. Множественная проверка, превысившая время, завершается ошибкой целиком — без частичных результатов, вся сумма возвращается.
`Множественная проверка — до 100 номеров`	Результаты сохраняют порядок и количество отправленных номеров. Для одного аккаунта одновременно выполняется одна множественная проверка; отправляйте следующий пакет после того, как вернётся предыдущий.

Коды ошибок

Код	Описание
`40000`	Неподдерживаемый тип сервиса или конфликтующие поля запроса
`40001`	Недопустимое тело JSON
`40002`	Недопустимый номер
`40100`	Ключ API отсутствует или недействителен
`40200`	Недостаточно средств на балансе
`42200`	Сейчас не удалось определить статус номера. `data` не возвращается, запрос не оплачивается
`42900`	Исчерпана квота использования или слишком много незавершённых заказов
`42901`	Все пять слотов одновременных запросов заняты, или в этом аккаунте уже выполняется множественная проверка; отправьте запрос после завершения одного из выполняющихся. Отклонённый запрос не оплачивается и содержит заголовок `Retry-After`
`50303`	Сервис сейчас работает на пределе мощности; списания нет. Подождите указанное в `Retry-After` число секунд и отправьте тот же запрос повторно
`50400`	Проверка не завершилась за отведённое время и не оплачивается; повторите её. Превышение времени пакета приводит к ошибке всего пакета и полному возврату суммы
`50300`	Техобслуживание сервиса проверки