CarrierLookup
Справочник

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

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

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

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

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

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

Заголовок аутентификации
X-API-Key: sk_your_api_key

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

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

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

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

Параметры

ПолеТипОписание
service_typestringКод продукта — один из продуктов, перечисленных ниже.
identifierstringОдиночная проверка: один номер телефона. Сервер нормализует его.
identifiersstring[]Множественная проверка: от 1 до 100 номеров телефонов. Ответ сохраняет этот порядок.

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

Определение исходного оператора

carrierтелефон

Узнайте, какому оператору номер был изначально выделен, а также тип линии и местоположение.

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

POST/api/v1/check
Запрос
curl -X POST "https://carrierlookup.online/api/v1/check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifier": "+17253100591" }'
{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "identifier": "+17253100591",
    "carrier": "T-Mobile",
    "underlying_carrier": "",
    "number_type": "Fixed Line or Mobile",
    "country_code": "US",
    "region": "NV",
    "city": "LAS VEGAS"
  }
}
Поля ответа
ПолеТипОписание
carrierstringОператор, которому номер был изначально выделен. Не текущий оператор после переноса.
underlying_carrierstringБазовый оператор, сообщённый поставщиком данных, если он отличается от выделенного; пустая строка, если поставщик его не предоставляет.
number_typestringТип линии, сообщённый поставщиком данных; пусто, если недоступен.
country_codestringКод страны ISO, к которой относится номер.
regionstringРегион выделения; пусто, если поставщик его не предоставляет.
citystringГород выделения; пусто, если поставщик его не предоставляет.

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

POST/api/v1/batch-check
Запрос
curl -X POST "https://carrierlookup.online/api/v1/batch-check" \
  -H "X-API-Key: sk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{ "service_type": "carrier", "identifiers": ["+17253100591", "12345"] }'
Ответ
{
  "code": 0,
  "msg": "ok",
  "data": {
    "service_type": "carrier",
    "total": 2,
    "succeeded": 1,
    "failed": 1,
    "results": [
      {
        "identifier": "+17253100591",
        "exists": true,
        "carrier": "T-Mobile",
        "underlying_carrier": "",
        "number_type": "Fixed Line or Mobile",
        "country_code": "US",
        "region": "NV",
        "city": "LAS VEGAS"
      },
      {
        "identifier": "12345",
        "exists": false
      }
    ]
  }
}
Поля ответа
ПолеТипОписание
existsbooleanПолучен ли результат по этому номеру. false означает, что формат недопустим, результат не определён или проверка не удалась; при false ни одно из полей ниже не возвращается.
carrierstringОператор, которому номер был изначально выделен. Не текущий оператор после переноса.
underlying_carrierstringБазовый оператор, сообщённый поставщиком данных, если он отличается от выделенного; пустая строка, если поставщик его не предоставляет.
number_typestringТип линии, сообщённый поставщиком данных; пусто, если недоступен.
country_codestringКод страны ISO, к которой относится номер.
regionstringРегион выделения; пусто, если поставщик его не предоставляет.
citystringГород выделения; пусто, если поставщик его не предоставляет.

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

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

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

Параметры

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

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

Глобальное определение оператора

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

Загрузите целый файл с номерами: оператор, базовый оператор, тип линии, страна, регион и город для каждого — те же поля, что и при определении оператора в реальном времени.

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

POST/api/v1/bulk-tasks
Запрос
curl -X POST "https://carrierlookup.online/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": 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://carrierlookup.online/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": 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"
  }
}
Столбцы результата
Полепример:Описание
identifier17253100591Отправленный номер в виде цифр с кодом страны, без знака плюс и пробелов (например, 17253100591).
carrierT-MobileОператор, которому номер был изначально выделен. Не текущий оператор после переноса.
underlying_carrierБазовый оператор, сообщённый поставщиком данных, если он отличается от выделенного; пусто, если поставщик его не предоставляет.
number_typeFixed Line or MobileТип линии, сообщённый поставщиком данных, например Fixed Line or Mobile; пусто, если недоступен.
country_codeUSКод страны ISO, к которой относится номер.
regionCAРегион выделения; пусто, если поставщик его не предоставляет.
cityLOS ANGELESГород выделения; пусто, если поставщик его не предоставляет.

Баланс

GET/api/v1/balance

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

Баланс

GET/api/v1/balance
Запрос
curl "https://carrierlookup.online/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Сейчас не удалось получить результат по этому номеру. Данные не возвращаются, запрос не оплачивается
42900Исчерпана квота использования или слишком много незавершённых заказов
42901Все пять слотов одновременных запросов заняты, или в этом аккаунте уже выполняется множественная проверка; отправьте запрос после завершения одного из выполняющихся. Отклонённый запрос не оплачивается и содержит заголовок Retry-After
50303Сервис сейчас работает на пределе мощности; списания нет. Подождите указанное в Retry-After число секунд и отправьте тот же запрос повторно
50400Проверка не завершилась за отведённое время и не оплачивается; повторите её. Превышение времени пакета приводит к ошибке всего пакета и полному возврату суммы
50300Техобслуживание сервиса запросов