Документация API

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

Для всех запросов нужен API-ключ в заголовке.

http

X-API-Key: YOUR_API_KEY

API-ключ доступен в консоли, в разделе «API Center». Полный ключ показывается только при создании; сразу сохраните его.

Формат ответа

Все эндпоинты возвращают JSON.

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

GET /v1/balance

Получить баланс

Возвращает текущий баланс USDT.

Пример ответа

json

{ "balance": "5.230000" }

POST /v1/detect

Проверка номеров (массив)

Отправьте массив номеров для проверки. Обрабатывается асинхронно.

От 1 000 до 2 000 000 номеров за запрос. Формат: +8613800138000.

Параметры

Поле	Тип	Обязательно	Описание
product	string	Да	Slug продукта. Смотрите список продуктов.
country	string	Да	Двухбуквенный код страны ISO 3166-1, например CN или US.
phones	array	Да	Массив номеров, от 1 000 до 2 000 000.

Пример ответа

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued. Poll GET /api/v1/tasks/xKj9aP3qLm7v for progress.",
  "summary": {
    "total": 5000,
    "cost_deducted": 0.500000
  }
}

POST /v1/detect/file

Проверка номеров (файл)

Загрузите TXT/CSV файл, один номер на строку, до 50 МБ.

Параметры

Content-Type: multipart/form-data

Поле	Тип	Обязательно	Описание
product	string	Да	Slug продукта
country	string	Да	ISO-код страны
file	file	Да	Файл TXT или CSV, один номер в строке, максимум 50 МБ.

Пример ответа

json

{
  "mode": "async",
  "task_id": "qH5rZ7Lp3Wm9",
  "message": "File queued (10000 numbers). Poll GET /api/v1/tasks/qH5rZ7Lp3Wm9 for progress.",
  "summary": {
    "total": 10000,
    "cost_deducted": 1.000000
  }
}

GET /v1/tasks/{task_id}

Статус задачи

Опрашивайте задачу каждые 3–5 секунд до completed или failed.

Пример ответа

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "whatsapp-active",
  "country": "CN",
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "cost_deducted": "0.500000",
  "cost_refunded": "0.000000",
  "result_available": true,
  "result_expires_at": "2026-05-02T10:00:00+00:00",
  "created_at": "2026-05-01T10:00:00+00:00"
}

Статус задачи

status	Описание
pending	В очереди, ожидает ресурсов.
processing	Проверка выполняется.
completed	Завершено. Результат готов к скачиванию.
failed	Выполнение завершилось ошибкой.

GET /v1/tasks/{task_id}/result

Ссылка на результат

Получите ссылку для скачивания результата. Файлы хранятся 7 дней по умолчанию (настраивается через result_retention_days).

Пример ответа

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0
  }
}

Коды ошибок

При ошибке проверьте HTTP статус и поле message.

HTTP	Ошибка	Решение
401	Unauthenticated	Проверьте наличие и корректность заголовка X-API-Key.
402	Insufficient balance.	Недостаточно баланса. Пополните счет и повторите запрос.
404	Not found	task_id не существует или принадлежит другому аккаунту.
422	Ошибка валидации	Проверьте обязательные поля, формат номеров и тип файла.
429	Too Many Requests	Для endpoints проверки действует лимит 10 запросов в минуту.

Продукты

Используйте slug в поле product при создании задачи.

Название продукта	Slug
Проверка номеров Amazon	`amazonValid`
Проверка email Amazon	`amazonemailValid`
Проверка номеров Apple ID	`appleidValid`
Проверка email Apple ID	`appleidEmailValid`
Проверка номеров BAND	`bandValid`
Проверка номеров Binance	`binanceValid`
Проверка email Binance	`binanceEmailValid`
Проверка номеров CoinW	`coinwValid`
Проверка email CoinW	`coinwEmailValid`
Проверка номеров Facebook	`fbValid`
Проверка email Facebook	`fbemailValid`
HLR-поиск	`hlr-lookup`
Проверка номеров HTX	`htxValid`
Проверка email HTX	`htxEmailValid`
Проверка номеров iMessage	`imessageValid`
Проверка номеров Instagram	`instagram`
Проверка email Instagram	`insEmailValid`
Проверка номеров KuCoin	`kucoinValid`
Проверка email KuCoin	`kucoin`
Возраст и пол LINE	`lineGender`
Проверка номеров LINE	`lineValid`
Number Checker	`linkednAll`
Number Checker	`linkedn`
Проверка номеров Microsoft	`microsoftValid`
Проверка номеров RCS	`RCSValid`
Проверка номеров Signal	`signalValid`
Проверка номеров Snapchat	`snapchatValid`
Полный профиль Telegram	`tgGender`
Проверка номеров Telegram	`tgValid`
Активность Telegram	`tgActive`
Поиск имени пользователя TikTok	`tkUsername`
Проверка номеров Viber	`viberValid`
Активность Viber	`viberActive`
Полный профиль WhatsApp	`wsGender`
Проверка номеров WhatsApp	`wsValid`
Активность WhatsApp	`wsActive`
Возраст и пол Zalo	`zaloGender`
Проверка номеров Zalo	`zaloValid`
Фильтр интернет-активности	`internet-activity-filter`
Проверка статуса номера	`phone-status-check`
Определение модели телефона	`phone-model-detection`
Phone Status Check（CN）	`cnActiveNumber`

Примеры

Скопируйте и запустите примеры cURL, заменив YOUR_API_KEY.

1. Получить баланс

bash

curl -X GET "https://api.bulkchecker.io/api/v1/balance" \
  -H "X-API-Key: YOUR_API_KEY"

2. Отправить проверку

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "whatsapp-active",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

3. Загрузить файл

bash

curl -X POST "https://api.bulkchecker.io/api/v1/detect/file" \
  -H "X-API-Key: YOUR_API_KEY" \
  -F "product=whatsapp-active" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

4. Проверить статус задачи

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_API_KEY"

5. Получить ссылку на скачивание

bash

curl -X GET "https://api.bulkchecker.io/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_API_KEY"