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

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

Создайте ключ на странице API-ключей, затем замените заполнитель ниже в своём терминале. Примеры — это просто текст; их копирование ничего не отправляет.

# API origin: https://api.numdetect.com
export NUMDETECT_API_KEY='YOUR_API_KEY'

• Отправляйте Authorization: Bearer <key> с каждым запросом. JSON-запросам также нужен Content-Type: application/json. Cookie, заголовок CSRF и заголовок Origin не требуются.
• Ключ может читать продукты, запускать одиночные и массовые проверки, читать их результаты и читать историю вашего баланса. Настройки аккаунта, ключи и пополнения управляются только в панели после входа.
• Можно создать до 10 ключей, например по одному на систему, и мгновенно удалить любой из них.

Храните ключи в окружении сервера. Не помещайте ключи в URL, скриншоты, общие журналы и закоммиченные исходные файлы.

Продукты

Прочитайте актуальный каталог, прежде чем выбирать ID продуктов. Ответ перечисляет все продукты в продаже с типом входных данных, ценами, минимумом для массовых проверок и поддерживаемыми странами.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/products" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

single и bulk показывают, доступен ли продукт для этого вида проверки сейчас. countries — это ["*"] для всех стран, список кодов стран или пустое значение для продуктов e-mail. Цены указаны в USD micros за проверку.

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

POST /api/v1/checks принимает один номер телефона или один адрес e-mail и список ID продуктов. Запрос ждёт, пока ответят все продукты (до примерно 45 секунд), и возвращает завершённую проверку.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"phone":"+12025550147","products":["whatsapp","telegram"]}'

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/checks" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H 'Content-Type: application/json' \
  -d '{"email":"[email protected]","products":["apple_email","spotify_email"]}'

Записывайте номера телефонов с кодом страны через +. Для номера без него добавьте в запрос "country": "GB" (код страны ISO).

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks/$CHECK_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/checks?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

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

POST /api/v1/bulk-jobs загружает файл как multipart form data. Файл делится на один список по каждой стране, и каждая страна проверяется каждым выбранным вами продуктом.

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -F "[email protected]" \
  -F "products=whatsapp,telegram" \
  -F "input_kind=phone" \
  -F "max_cost=50000000" \
  -F "column=0" \
  -F "header=true"

• file: CSV в UTF-8 или обычный текст, до 100 МБ и 1 000 000 строк. Остальные столбцы сохраняются и возвращаются в файле результатов.
• input_kind — это phone или email. column — столбец с номерами, нумерация с 0 (по умолчанию 0); header=true пропускает первую строку.
• country (необязательно) используется для номеров телефонов, записанных без кода страны. Номера, начинающиеся с + или 00, сохраняют свою страну.
• max_cost — это максимальная сумма, которую вы готовы заплатить, в USD micros. Задание отклоняется, и ничего не списывается, если его стоимость окажется выше или баланса недостаточно.

Статус и результаты массового задания

Читайте задание, пока status не станет completed, failed или cancelled. Большие списки могут обрабатываться долго, поэтому опрашивайте раз в минуту-две или используйте webhook.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Скачайте файл результатов

Когда result_ready равен true, GET /result возвращает ссылку для скачивания, действующую 10 минут. Для самой ссылки ключ не нужен. Запрашивайте новую ссылку всякий раз, когда нужно скачать снова.

url=$(curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/result" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY" | jq -r .url)
curl --fail --silent --show-error --output result.csv "$url"

result.csv сохраняет каждую исходную строку в исходном порядке и добавляет numdetect_status (valid, duplicate или invalid), numdetect_country и по одному столбцу на каждый продукт со значениями yes, no, unknown, unsupported, failed или cancelled.

Отмена выполняющегося задания

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

curl --fail-with-body --silent --show-error -X POST "https://api.numdetect.com/api/v1/bulk-jobs/$JOB_ID/cancel" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

Webhook

Укажите URL webhook на странице настроек аккаунта, чтобы получать уведомление о завершении массового задания. Мы отправляем один HTTPS POST на каждое завершённое задание:

{
  "type": "bulk_job.finished",
  "data": {
    "id": "10000000-0000-4000-8000-000000000003",
    "status": "completed",
    "total_rows": 1000,
    "valid_rows": 982,
    "charged": 245500,
    "completed_at": "2026-11-11T08:30:00Z"
  }
}

Каждый запрос содержит заголовки webhook-id, webhook-timestamp и webhook-signature. Подпись — это v1, за которым следует Base64-представление HMAC-SHA256 от "<webhook-id>.<webhook-timestamp>.<body>", вычисленного с вашим секретом подписи (whsec_…, Base64 после префикса). Сравните её, прежде чем доверять телу запроса.

Отвечайте любым статусом 2xx. Неудачные доставки повторяются несколько раз с интервалом в несколько минут. Считайте webhook-id уникальным, так как повторная доставка может прийти дважды.

Стоимость и баланс

Одиночная проверка оплачивается по цене за каждый продукт с однозначным ответом. Ответы unknown и failed бесплатны.

Массовое задание резервирует свою стоимость при отправке: для каждой страны и продукта — max(корректные номера, оптовый минимум продукта) × оптовая цена. Завершённый список оплачивается полностью, включая строки unknown. Список, который не выполнен или отменён, возвращается на ваш баланс. Повторяющиеся и некорректные строки, а также страны, которые продукт не поддерживает, бесплатны.

Суммы — целые числа в USD micros: 1 USD = 1 000 000 micros.

curl --fail-with-body --silent --show-error -X GET "https://api.numdetect.com/api/v1/balance-logs?limit=20" \
  -H "Authorization: Bearer $NUMDETECT_API_KEY"

POST /checks и POST /bulk-jobs требуют заголовок Idempotency-Key (до 128 символов). Используйте новый ключ для каждого нового запроса. Если ответ потерялся, отправьте тот же запрос с тем же ключом: вы получите первый результат, а не второе списание.

Ошибки

Ошибки имеют вид {error: {code, message, request_id}}. Ориентируйтесь на стабильный code, а не на message, и указывайте request_id при обращении в поддержку.

Получить API-ключМассовые проверкиНастройки webhookОплата