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

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

Для всех запросов нужен API-ключ в заголовке. The public product catalog does not require authentication.

http

X-API-Key: YOUR_KEY_HERE

Authorization: Bearer YOUR_KEY_HERE

Ключ состоит из 51 символа: префикс zn_ и 48 случайных символов. Ключи, выданные ранее с префиксом ck_, остаются действительными.

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

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

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

Пример ответа в реальном времени

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "status": "succeeded",
  "replayed": false,
  "results": []
}

Пример пакетного ответа

json

{
  "mode": "async",
  "task_id": "xKj9aP3qLm7v",
  "message": "Task queued."
}

GET /v1/balance

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

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

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

json

{ "balance": "5.230000" }

GET /v1/products

Продукты

Открытый каталог товаров; API-ключ не требуется. Он возвращает активные товары реального времени и пакетные товары, их серии и минимальное количество. Изучите его перед отправкой.

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

json

{
  "data": [
    {
      "id": 101,
      "slug": "whatsapp-realtime",
      "name": "WhatsApp Number Checker",
      "name_translations": { "zh_CN": "WhatsApp 注册检测" },
      "mode": "realtime",
      "series": "phone",
      "min_phones": 1
    }
  ]
}

GET /v1/api-key

Сведения об API-ключе

Возвращает метаданные API-ключа аутентифицированного аккаунта. Ключ в открытом виде никогда не возвращается.

json

{
  "api_key_id": 42,
  "masked_key": "ck_••••••••••••••••••••••••••••••••••••••••••••••••",
  "last_used": "2026-09-05T10:00:00Z",
  "created_at": "2026-08-01T09:00:00Z"
}

Ключ в открытом виде показывается только один раз при создании или ротации; этот endpoint возвращает только маскированное значение.

Коды ошибок

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

Тело ошибки

json

{
  "code": "insufficient_balance",
  "message": "Insufficient balance for this submission."
}

Бизнес-ошибки всегда возвращают машиночитаемый code для программной обработки. Некорректные параметры (валидация) и несуществующие маршруты возвращают стандартный формат Laravel: { "message": "...", "errors": { ... } }. Проверяйте входные данные до отправки.

Ошибка

code	HTTP	Описание
unauthorized	401	API-ключ отсутствует, неверен или деактивирован.
account_banned	403	Аккаунт заблокирован. Обратитесь в поддержку.
invalid_realtime_request	400	Некорректный realtime-запрос (например, номер без международного префикса +, если country не указан).
idempotency_key_required	400	Realtime-запросы требуют заголовок Idempotency-Key.
invalid_idempotency_key	422	Недопустимый Idempotency-Key: 1-128 символов из букв, цифр и . _ : -
idempotency_conflict	409	Тот же Idempotency-Key использован с другим содержимым запроса.
request_in_progress	409	Идентичный realtime-запрос ещё обрабатывается. Повторите чуть позже (Retry-After: 1).
empty_input	422	Загруженный файл не содержит пригодных строк.
product_not_found	422	Указанный slug продукта не существует или неактивен.
product_mode_not_supported	422	Этот эндпоинт не принимает такой режим продукта (realtime-продукты не для массовых эндпоинтов).
invalid_country	422	Продукт не поддерживает указанную страну.
too_few_numbers	422	Отправка ниже минимума продукта.
too_many_numbers	422	Отправка превышает максимум платформы.
insufficient_balance	402	Недостаточно средств. Пополните баланс и повторите.
realtime_disabled	403	Realtime-проверка не включена для этого аккаунта.
realtime_rate_limited	429	Превышен лимит realtime-запросов. Соблюдайте retry_after.
product_pricing_unavailable	503	Цены для этого продукта ещё не настроены. Обратитесь в поддержку.
detection_capacity_unavailable	503	Сейчас нет доступной ёмкости для проверки. Повторите позже.
realtime_route_unavailable	503	Нет доступного realtime-маршрута. Повторите позже.
realtime_fact_cache_unavailable	503	Зависимость realtime временно недоступна. Повторите позже.
realtime_rate_limiter_unavailable	503	Лимитер временно недоступен. Повторите позже.
not_found	404	task_id не существует или принадлежит другому аккаунту.
result_not_ready	422	Задача ещё не завершена или файл результата ещё не создан.
result_expired	404	Срок действия файла результата истёк, файл отсутствует или недоступен.
validation_failed	422	Проверьте обязательные поля, формат номеров и тип файла.
internal_error	500	Внутренняя ошибка сервера. Повтор с тем же Idempotency-Key безопасен.

Лимиты запросов

Запросы к API ограничиваются по API-ключу и по группе эндпоинтов:

Эндпоинты	Лимит
GET /v1/products · GET /v1/balance · GET /v1/api-key · GET /v1/tasks/{token} · GET /v1/tasks/{token}/result · GET /v1/tasks/{token}/download	60 запросов / минуту на API-ключ (120 / минуту на IP)
Эндпоинты: POST /v1/detect · POST /v1/detect/file · POST /v1/quotes/bulk	10 запросов / минуту на API-ключ (30 / минуту на IP)
Эндпоинты: POST /v1/realtime/quote/{series} · POST /v1/realtime/check/{series} · POST /v1/realtime/detect	Token bucket на API-ключ: всплеск 60, пополнение 1/с (≈60 / минуту устойчиво); на аккаунт: всплеск 120, пополнение 2/с. Уровень IP допускает 180 / минуту. Каждый ответ содержит заголовок X-RateLimit-Remaining.

При превышении лимита API возвращает 429 с заголовком Retry-After (realtime-ответы также содержат поле retry_after). Приостановите запросы на указанное число секунд, затем продолжайте с экспоненциальной задержкой.

POST /v1/realtime/check/{series}

Проверка одного идентификатора в реальном времени

Синхронная проверка одного телефона или адреса электронной почты. В запросе можно выбрать несколько продуктов реального времени одной серии по ID; slug пакетных продуктов не используется.

Idempotency-Key обязателен. Повтор того же запроса с тем же ключом не списывает средства дважды; изменение данных возвращает 409. cached=true означает повторно использованный результат.

Параметры

Поле	Тип	Обязательно	Описание
series	path	Да	Серия: phone или email; должна совпадать с серией выбранного realtime-продукта.
identifier	string	Да	Один идентификатор: номер E.164 или корректный адрес электронной почты.
country	string	Нет	Только для телефона: для полного E.164 необязательно; для национального номера нужен соответствующий ISO-код страны. Для почты оставьте пустым.
product_ids	array<int>	Да	Массив из 1–10 ID продуктов реального времени.

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

json

{
  "request_id": "8c1e4f91-7bd8-4d7e-a3ae-3d7e5b0c6c11",
  "identifier": "+8613800138000",
  "series": "phone",
  "status": "succeeded",
  "request_status": "completed",
  "total_reserved": 0.004000,
  "total_charged": 0.004000,
  "total_refunded": 0.000000,
  "charged_amount": 0.004000,
  "refunded_amount": 0.000000,
  "replayed": false,
  "results": [
    {
      "product_id": 101,
      "product": "whatsapp-realtime",
      "result": "valid",
      "cached": false,
      "billing_status": "charged",
      "charged_amount": 0.004000,
      "refunded_amount": 0.000000,
      "checked_at": "2026-09-05T10:00:00Z",
      "error_code": null
    }
  ]
}

Пример cURL

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/phone" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"+8613800138000","country":"CN","product_ids":[101,102]}'

bash

curl -X POST "https://api.zelnum.com/api/v1/realtime/check/email" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Idempotency-Key: UNIQUE_REQUEST_ID" \
  -H "Content-Type: application/json" \
  -d '{"identifier":"[email protected]","country":null,"product_ids":[201]}'

Каждый продукт использует зафиксированную цену за проверку, включая попадание в кэш. valid и invalid оплачиваются; unknown, тайм-аут и занятые элементы возвращаются.

Частично успешная комбинация возвращает HTTP 200 и status=partial_succeeded; при полном сбое — status=failed. Проверяйте billing_status и error_code каждого элемента.

Idempotency-Key ограничен 191 байтом и действует для пользователя. После тайм-аута или 500 повторите исходные данные с исходным ключом. Результаты хранятся 30 дней по умолчанию.

HTTP	code	Значение / действие
400	invalid_realtime_request / idempotency_key_required	Исправьте номер, продукты или ключ; предоплаты не было.
401 / 403	unauthorized / account_banned / realtime_disabled	Проверьте ключ, состояние аккаунта и доступ; предоплаты не было.
402	insufficient_balance	Недостаточно средств; комбинация не запускается.
409	request_in_progress / idempotency_conflict	Повторите после Retry-After; другой запрос не может использовать тот же ключ.
429	realtime_rate_limited	Подождите время Retry-After; предоплаты не было.
503	realtime_route_unavailable / realtime_fact_cache_unavailable / realtime_rate_limiter_unavailable	Маршрут, кэш или лимитер недоступен; повторите позже.
500	internal_error	Результат неясен. Повторите с исходным ключом, не создавая новый.

error_code указывает на сбой провайдера, лимита канала, срока, кэша или защиты конкуренции. Ошибочные элементы не оплачиваются.

Endpoint совместимости POST /v1/realtime/detect временно сохраняется для старых клиентов. Новые интеграции должны использовать /v1/realtime/check/phone или /v1/realtime/check/email.

Продукты · Одиночный (реальное время)

Товары реального времени выбираются по идентификатору товара и серии; не используйте slug пакетных товаров.

Название продукта	Series	Идентификатор	Минимум
Проверка номера Amazon	`phone`	`#53`	1
Проверка email для Amazon	`email`	`#54`	1
Проверка номера Apple ID	`phone`	`#57`	1
Проверка email для Apple ID	`email`	`#58`	1
Проверка номера BAND	`phone`	`#60`	1
Проверка номера Facebook	`phone`	`#51`	1
Проверка email для Facebook	`email`	`#52`	1
Проверка номера Instagram	`phone`	`#48`	1
Проверка email для Instagram	`email`	`#49`	1
Проверка номера Microsoft	`phone`	`#59`	1
Проверка номера Telegram	`phone`	`#50`	1
Проверка номера Viber	`phone`	`#55`	1
Проверка номера WhatsApp	`phone`	`#47`	1
Проверка телефонного номера в X	`phone`	`#61`	1

POST /v1/detect

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

Отправьте массив телефонов или адресов электронной почты для асинхронной пакетной проверки. Стоимость резервируется, необработанные элементы возвращаются.

Минимум задаётся продуктом, максимум платформы — 2 000 000. Для email country не указывается, для телефона обязателен.

HTTP 202 Accepted

Параметры

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

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

json

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

POST /v1/detect/file

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

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

HTTP 202 Accepted

Параметры

Content-Type: multipart/form-data

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

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

json

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

GET /v1/tasks/{token}

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

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

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

json

{
  "task_id": "xKj9aP3qLm7v",
  "status": "completed",
  "progress": 100,
  "product": "YOUR_PRODUCT_SLUG",
  "country": "CN",
  "submitted": 5000,
  "prefiltered": 0,
  "deduped": 0,
  "total": 5000,
  "processed": 5000,
  "valid": 3800,
  "invalid": 1200,
  "unknown": 0,
  "unknown_processed": 0,
  "unknown_unprocessed": 0,
  "stage": "completed",
  "stage_seconds": 12,
  "last_progress_at": "2026-09-05T10:00:12+00:00",
  "failure_message": null,
  "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/{token}/result

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

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

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

json

{
  "task_id": "xKj9aP3qLm7v",
  "download_url": "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/download",
  "expires_at": "2026-05-02T10:00:00+00:00",
  "summary": {
    "submitted": 5000,
    "prefiltered": 0,
    "deduped": 0,
    "total": 5000,
    "valid": 3800,
    "invalid": 1200,
    "unknown": 0,
    "unknown_processed": 0,
    "unknown_unprocessed": 0
  }
}

GET /v1/tasks/{token}/download

Скачать результат

Скачивает файл результата завершённой задачи, пока не истёк срок хранения.

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

Content-Type: application/zip (or text/csv for a single result).

Этот endpoint передаёт файл вместо JSON. Он возвращает 404/422, если задача не готова, истекла, недоступна или принадлежит другому аккаунту.

Продукты · Пакетный (асинхронный)

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

Название продукта	Идентификатор	Минимум
Проверка номера Amazon	`amazonValid`	500
Проверка email для Amazon	`amazonEmailValid`	1000
Проверка номера Apple ID	`appleidValid`	2000
Проверка email для Apple ID	`appleidEmailValid`	1000
Проверка номера BAND	`bandValid`	500
Проверка номера Binance	`binanceValid`	2000
Проверка email для Binance	`binanceEmailValid`	2000
Проверка номера CoinW	`coinwValid`	2000
Проверка email для CoinW	`coinwEmailValid`	2000
Проверка номера Facebook	`fbValid`	500
Проверка email для Facebook	`fbEmailValid`	1000
Проверка номера HTX	`htxValid`	1000
Проверка email для HTX	`htxEmailValid`	2000
Проверка номера iMessage	`imessageValid`	2000
Проверка номера Instagram	`insValid`	500
Проверка email для Instagram	`insEmailValid`	1000
Проверка номера KuCoin	`kucoinValid`	1000
Проверка email для KuCoin	`kucoinEmailValid`	2000
Возраст и пол в LINE	`lineGender`	2000
Проверка номера LINE	`lineValid`	2000
Полный профиль Linkedin	`linkedinGender`	2000
Проверка номера Linkedin	`linkedinValid`	2000
Проверка номера Microsoft	`microsoftValid`	500
Проверка поддержки RCS	`rcsValid`	1000
Проверка номера Signal	`signalValid`	2000
Проверка номера Snapchat	`snapchatValid`	500
Полный профиль Telegram	`tgGender`	500
Проверка номера Telegram	`tgValid`	1000
Проверка активности Telegram	`tgActive`	500
Поиск имени пользователя TikTok	`tiktokUsername`	2000
Проверка номера Viber	`viberValid`	1000
Проверка активности Viber	`viberActive`	1000
Полный профиль WhatsApp	`waGender`	1000
Проверка номера WhatsApp	`waValid`	1000
Данные об активности WhatsApp	`waActive`	500
Проверка телефонного номера в X	`twitterValid`	2000
Проверка email для X	`twitterEmailValid`	2000
Возраст и пол в Zalo	`zaloGender`	500
Проверка номера Zalo	`zaloValid`	2000
Фильтр интернет-активности	`live-activity-filter`	2000
Проверка статуса номера	`phone-status-check`	2000
Телефон включён/выключен	`phone-onoff-check`	1500
Определение модели телефона	`phone-model-detection`	500
Поиск HLR	`hlr-lookup`	2000

Примеры

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

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

bash

curl -X GET "https://api.zelnum.com/api/v1/balance" \
  -H "X-API-Key: YOUR_KEY_HERE"

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

bash

curl -X POST "https://api.zelnum.com/api/v1/detect" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "YOUR_PRODUCT_SLUG",
    "country": "CN",
    "phones": ["+8613800138000", "+8613900139000"]
  }'

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

bash

curl -X POST "https://api.zelnum.com/api/v1/detect/file" \
  -H "X-API-Key: YOUR_KEY_HERE" \
  -F "product=YOUR_PRODUCT_SLUG" \
  -F "country=CN" \
  -F "file=@/path/to/numbers.txt"

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

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v" \
  -H "X-API-Key: YOUR_KEY_HERE"

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

bash

curl -X GET "https://api.zelnum.com/api/v1/tasks/xKj9aP3qLm7v/result" \
  -H "X-API-Key: YOUR_KEY_HERE"