Справочник

NumDetect Справочник API

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

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

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

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

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

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

X-API-Key: sk_your_api_key

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

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

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 символов. Повторная отправка с тем же ключом возвращает исходную задачу вместо создания новой.

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

Валидация номеровnumber_validation_batchЧистый список — начало следующей кампании. Проверьте действительность номеров и сигналы активации, чтобы найти записи, заслуживающие внимания, а затем используйте структурированный результат для очистки списков, обновления CRM и проверок перед рассылкой — так каждое действие начинается с более ясных данных.Страница продукта
Активность номеровnumber_activity_batchПусть следующий контакт начинается с сигнала активности. Найдите недавнюю активность по всему списку номеров, отделите неактивные записи от номеров, заслуживающих внимания, и используйте результат для планирования реактивации, сегментации и приоритетов рассылки.Страница продукта
Ценные пользователиnumber_high_value_batchНайдите записи, которые стоит проверить в первую очередь. Сочетание характеристик устройств высокого класса и недавней сетевой активности даёт сигнал «потенциально ценный пользователь» (true/false) для расстановки приоритетов в обслуживании, программах лояльности и кампаниях; это сигнал обнаружения, а не доказательство дохода или покупок.Страница продукта
Активность в e-commercenumber_ecommerce_batchНачните следующую коммерческую кампанию с более точной аудиторией. Найдите доступные сигналы активности в e-commerce, сформируйте сегменты аудитории и ремаркетинга вокруг записей, заслуживающих внимания, и помните о границах: результат не является заказом, намерением покупки или записью об активности на платформе.Страница продукта
Глобальный поиск оператораcarrier_batchПревратите список номеров в данные, готовые для маршрутизации. Дополните международные записи оператором, базовым оператором, типом линии, страной, регионом и городом, а затем используйте обогащённый результат для маршрутизации, регионального анализа, сегментации и обновления CRM.Страница продукта

Валидация номеров

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

Чистый список — начало следующей кампании. Проверьте действительность номеров и сигналы активации, чтобы найти записи, заслуживающие внимания, а затем используйте структурированный результат для очистки списков, обновления CRM и проверок перед рассылкой — так каждое действие начинается с более ясных данных.

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

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_validation_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

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

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591), — стабильный ключ для сопоставления результатов с клиентом, лидом или записью CRM. Сохраняйте его, чтобы отслеживать исходный список и массово записывать результаты обратно; само по себе это поле не подтверждает, что с номером можно связаться.
`activated`	true	Сигнал активации, возвращённый этой проверкой. Используйте его, чтобы находить записи для проверки перед рассылкой, формировать очереди очистки и поддерживать сегментацию в CRM; сочетайте его с данными о согласии, источнике и взаимодействиях, а не считайте гарантией соединения или доставки. Значения: true или false.

Активность номеров

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

Пусть следующий контакт начинается с сигнала активности. Найдите недавнюю активность по всему списку номеров, отделите неактивные записи от номеров, заслуживающих внимания, и используйте результат для планирования реактивации, сегментации и приоритетов рассылки.

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

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_activity_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

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

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591); используется для записи результата активности обратно в список, запись клиента или лида. Служит только для сопоставления и отслеживания; не содержит времени активности, частоты или сведений о взаимодействиях.
`activated`	true	Доступный сигнал активности, который помогает командам расставлять приоритеты проверки, создавать метки аудитории и планировать ритм реактивации. Это не число активных дней, не частота и не конкретное время наблюдения; отсутствие сигнала не означает, что человек никогда не ответит. Значения: true или false.

Ценные пользователи

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

Найдите записи, которые стоит проверить в первую очередь. Сочетание характеристик устройств высокого класса и недавней сетевой активности даёт сигнал «потенциально ценный пользователь» (true/false) для расстановки приоритетов в обслуживании, программах лояльности и кампаниях; это сигнал обнаружения, а не доказательство дохода или покупок.

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

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_high_value_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

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

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны (например, 12017200001); используется для сопоставления сигнала ценности с загруженной записью и её отслеживания в CRM или очереди проверки. Не содержит данных о личности, модели устройства или иных сведений персонального профиля.
`activated`	true	Вспомогательный сигнал true/false, основанный на характеристиках устройств высокого класса и недавней сетевой активности. Помогает командам программ лояльности, поддержки и маркетинга расставлять приоритеты проверки, но не подтверждает доход, активы, покупательскую способность или фактические расходы.

Активность в e-commerce

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

Начните следующую коммерческую кампанию с более точной аудиторией. Найдите доступные сигналы активности в e-commerce, сформируйте сегменты аудитории и ремаркетинга вокруг записей, заслуживающих внимания, и помните о границах: результат не является заказом, намерением покупки или записью об активности на платформе.

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

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "number_ecommerce_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

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

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591); используется для связи сигнала активности в e-commerce с записями клиентов, лидов или аудитории. Позволяет маркетинговым командам объединять результат с собственными данными о согласии, просмотрах, заказах и участии в программах лояльности; не содержит информации о заказах или товарах.
`activated`	true	Доступный сигнал активности в e-commerce, помогающий сфокусировать проверку аудитории, подготовку списков для ремаркетинга и планирование тестов контента. Не означает заказ, сумму транзакции, намерение покупки или конкретную активность на платформе. Значения: true или false.

Глобальный поиск оператора

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

Превратите список номеров в данные, готовые для маршрутизации. Дополните международные записи оператором, базовым оператором, типом линии, страной, регионом и городом, а затем используйте обогащённый результат для маршрутизации, регионального анализа, сегментации и обновления CRM.

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

POST/api/v1/bulk-tasks

Запрос

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

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "processing",
    "country": "US",
    "submitted_lines": 509,
    "total": 509,
    "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://numdetect.com/api/v1/bulk-tasks/3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13" \
  -H "X-API-Key: sk_your_api_key"

Ответ

{
  "code": 0,
  "msg": "ok",
  "data": {
    "id": "3f9c2a7d8e4b4c1a9f0e6b2d5c8a7e13",
    "product": "carrier_batch",
    "status": "success",
    "country": "US",
    "submitted_lines": 509,
    "total": 500,
    "invalid_cnt": 3,
    "no_code_cnt": 0,
    "other_country_cnt": 0,
    "duplicate_cnt": 6,
    "preparing": false,
    "success_cnt": 495,
    "failure_cnt": 5,
    "result_url": "https://…/result.csv",
    "created_at": "2026-09-08T09:30:00Z"
  }
}

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

Поле	пример:	Описание
`identifier`	17253100591	Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591), — ключ сопоставления для записи данных об операторе, линии и географии обратно в исходный список. Храните рядом собственные столбцы источника, чтобы команды маршрутизации, поддержки и CRM могли отследить проверку, обработать дубликаты и обновить нужного клиента или лида. Поле идентифицирует запись, но не доказывает доступность номера.
`carrier`	T-Mobile	Название оператора, обслуживающего абонента, если его удаётся определить. Может обогащать записи CRM, поддерживать маршрутизацию обслуживания, помогать анализировать состав номеров и показывать распределение списка по операторам. Используйте его как операционный контекст, а не как доказательство доступности или текущего использования. Пустое значение означает, что в этой проверке пригодное название не получено; это не доказывает отсутствие оператора.
`underlying_carrier`		Базовый оператор сети, если его удаётся определить; полезен для понимания ситуаций с реселлерами, виртуальными операторами и перенесёнными номерами. Может отличаться от оператора, обслуживающего абонента, и это различие помогает командам разбираться с вопросами маршрутизации или принадлежности. Это не текущий статус сотовой сети и не сигнал соединения в реальном времени.
`number_type`	Fixed Line or Mobile	Возвращённый тип линии, например mobile, fixed line или другая распознаваемая категория. Используйте его, чтобы разделять мобильные и фиксированные номера, планировать маршрутизацию обслуживания, проверять соответствие каналу и добавлять полезный сегмент в CRM. Это не результат соединения; пустое или неизвестное значение оставляйте на проверку, а не считайте ошибкой.
`country_code`	US	Возвращённый код страны или территории для группировки международных списков, применения маршрутизации и бизнес-правил на уровне страны и построения региональных отчётов. Описывает контекст нумерации, а не текущую страну, физическое местоположение или гражданство человека. Случаи использования за рубежом и виртуальные номера следует сверять с собственными данными о клиентах.
`region`	CA	Регион, штат или провинция, если доступны. Помогает анализировать охват рынка, группировать списки по регионам, распределять обслуживание и готовить операционные отчёты. Данные основаны на контексте номера и сети, а не на текущем местоположении, поэтому не следует считать их текущим регионом пользователя; отсутствующие или межрегиональные значения требуют обычной бизнес-проверки.
`city`	LOS ANGELES	Город, если доступен. Помогает улучшить региональную отчётность, выявить состав списка, поддержать локальные операции и заполнить недостающее поле в CRM. Распределение номеров, их перенос, виртуальные номера и различия в источниках могут влиять на точность на уровне города, поэтому важные решения следует сверять с данными, предоставленными пользователем, или имеющимися бизнес-записями.

Баланс

GET/api/v1/balance

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

Баланс

GET/api/v1/balance

Запрос

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

Ответ

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

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

Массовые задачи принимаются до начала обработки. По возвращаемому статусу задачи решайте, продолжать опрос или обрабатывать ошибку.

Поле	Описание
`5 одновременных запросов на пользователя`	Отправка задачи занимает один слот запроса. Если у аккаунта нет свободного слота, API возвращает 42901 с заголовком Retry-After; подождите и отправьте файл повторно.
`Опрашивайте, а не ждите`	Отправка задачи возвращает ответ сразу. Пока задача обрабатывается, опрашивайте её статус не чаще одного раза в 30 секунд.
`Размер задачи зависит от продукта`	У каждого продукта свой минимальный и максимальный размер файла — они указаны в разделе задач.

Коды ошибок

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