API v1 · JSON

Проверка номера
одним запросом

Валидность, тип линии, страна, ISO-код и первоначальный оператор диапазона.

POST/api/v1/verify

API работает

OpenAPI-схема ↗

Быстрый старт

Первый запрос

Авторизация. Передавайте ключ в X-API-Key. Также поддерживается Authorization: Bearer.

Открыть кабинет →

curl -X POST "https://number.boostclicks.tech/api/v1/verify" \
  -H "X-API-Key: npi_live_..." -H "Content-Type: application/json" \
  -d '{"phone":"+14155552671"}'

import requests
API_URL = "https://number.boostclicks.tech/api/v1/verify"
API_KEY = "npi_live_..."
response = requests.post(API_URL, headers={"X-API-Key": API_KEY},
    json={"phone": "+14155552671"}, timeout=10)
print(response.json())

const API_URL = "https://number.boostclicks.tech/api/v1/verify";
const API_KEY = "npi_live_...";
const response = await fetch(API_URL, {
  method: "POST", headers: {"X-API-Key": API_KEY, "Content-Type": "application/json"},
  body: JSON.stringify({phone: "+14155552671"}),
});
const result = await response.json();

Тело запроса

Параметры

Поле	Обязательно	Описание
`phone`	Да	Строка до 64 символов. Рекомендуется E.164 с ведущим `+`.
`default_country`	Нет	Двухбуквенный ISO-код. Нужен только для номера без `+`.

Международный{"phone":"+442079460018"}

Национальный{"phone":"020 7946 0018","default_country":"GB"}

HTTP 200

Варианты ответа

Все обработанные номера возвращают 200 OK. Результат самой проверки находится в phone_valid.

Валидный мобильный200 OK

{
  "phone_valid": true,
  "phone_type": "mobile",
  "carrier": "T-Mobile USA, Inc.",
  "country": "United States",
  "country_code": "US"
}

Оператор неизвестен200 OK

{
  "phone_valid": true,
  "phone_type": "fixed_line_or_mobile",
  "carrier": null,
  "country": "United States",
  "country_code": "US"
}

Распознан, но невалиден200 OK · 1 проверка

{
  "phone_valid": false,
  "phone_type": "unknown",
  "carrier": null,
  "country": null,
  "country_code": null
}

Это не ошибка запроса. Номер разобран, но не соответствует плану нумерации; проверка списывается.

Контракт

Поля ответа

phone_valid

boolean — соответствует ли номер нумерационному плану. Не подтверждает активность или доступность SIM-карты.

phone_type

string — mobile, fixed_line, fixed_line_or_mobile, toll_free, premium_rate, shared_cost, voip, personal_number, pager, uan, voicemail или unknown.

carrier

string | null — первоначальный держатель диапазона, не обязательно текущая сеть после переноса номера.

country

string | null — название страны на английском языке.

country_code

string | null — код ISO 3166-1 alpha-2: US, GB, RU.

Контроль расхода

Лимиты и заголовки

В заголовках успешного ответа указан актуальный остаток после списания.

X-Request-IDID для диагностики

X-RateLimit-LimitЛимит запросов в минуту

X-RateLimit-RemainingОстаток запросов в минуте

X-Quota-LimitБесплатный лимит в месяце

X-Quota-RemainingОстаток в месяце

X-Daily-Quota-LimitБесплатный лимит в сутки

X-Daily-Quota-RemainingОстаток сегодня

X-Credit-BalanceБаланс кредитов

X-Charge-Sourcefree или credit

Списание: сначала бесплатные 100 проверок в сутки и 500 в месяц, затем кредиты. Один кредит — одна проверка.

Неуспешные ответы

Ошибки и действия

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": [{"field":"phone","message":"This field is required.","code":"required"}]
  }
}

HTTP	Код	Когда	Что делать
401	`authentication_required`	Ключ не передан	Добавить заголовок авторизации.
401	`invalid_api_key`	Ключ неверен или отозван	Проверить или выпустить новый.
401	`email_verification_required`	Почта не подтверждена	Подтвердить email.
403	`subscription_required`	Нет тарифа	Обратиться в поддержку.
403	`plan_inactive`	Тариф отключён	Обратиться в поддержку.
405	`method_not_allowed`	Использован не POST	Не передавать номер в URL.
422	`validation_error`	Нет поля или неверный формат	Исправить поля из `details`.
422	`invalid_phone`	Строку нельзя разобрать	Передать E.164 или `default_country`.
429	`rate_limit_exceeded`	Минутный лимит исчерпан	Ждать `Retry-After`.
429	`quota_exhausted`	Нет лимита и кредитов	Пополнить баланс.
503	`rate_limit_unavailable`	Защитный контур недоступен	Повторить с задержкой.

Надёжная интеграция

Когда повторять запрос

Повторяйте

429 rate_limit_exceeded — через Retry-After. Для 503 используйте паузы 1, 2, 4 и 8 секунд.

Не повторяйте без изменений

401, 403, 405 и 422 требуют исправить ключ, доступ, метод или данные.