Skip to main content
GET
API проверки телефонных номеров
Использовать очень просто: передайте API-ключ и номер телефона. API вернёт, является ли номер структурно валидным, а при валидном номере — нормализованные форматы E.164 и дополнительные данные: тип линии, подсказки по местоположению, оператора, часовые пояса и признаки дозвона, если доступны.
valid: true означает, что номер соответствует региональным правилам формата (длина, префикс, синтаксис). Это не подтверждает, что линия активна, назначена абоненту или доступна для связи. Для проверки статуса линии в реальном времени нужен отдельный lookup у оператора, который выходит за рамки этого API.

Начало работы

REST

API проверки телефонных номеров, как и все API Cleariflow, построен на REST. Он использует предсказуемые URL, ориентированные на ресурсы, и HTTP-коды статуса для указания ошибок.

HTTPS

API проверки телефонных номеров требует защиты всех соединений с помощью TLS 1.2 или выше.

Версии API

Все API Cleariflow версионируются. API проверки телефонных номеров сейчас на версии 1.

Ваш API-ключ

API-ключ — уникальный ключ аутентификации для доступа к API проверки телефонных номеров Cleariflow. У каждого API Cleariflow свой ключ, поэтому для Phone Validation и Email Validation, например, нужны разные ключи. Для аутентификации добавьте ключ к базовому URL.

Базовый URL

Что означает valid

Вымышленные американские номера 555 и другие структурно валидные, но не назначенные диапазоны могут по-прежнему возвращать valid: true. Поля carrier и location заполняются в основном для номеров US/CA и часто пусты для других регионов.

Эндпоинт проверки

API требует ваш уникальный API-ключ и номер телефона для проверки:
Валидный ответ (phone=14155552671, country=US):
Невалидный ответ (phone=123, country=US):

Параметры запроса

String
обязательно
Ваш уникальный API-ключ. У каждого пользователя уникальные ключи для каждого API Cleariflow, поэтому ключ Phone Validation не будет работать, например, с API геолокации IP.
String
обязательно
Номер телефона для проверки.
String
Необязательная подсказка ISO 3166-1 alpha-2 для национальных номеров без ведущего +. Например, country=US помогает разобрать 4155552671. Номера с международным префиксом разбираются по коду страны; определённый country.code в ответе может отличаться от этой подсказки (например, GG для некоторых мобильных диапазонов +44).

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

Ответ API возвращается в универсальном лёгком формате JSON.
String
Нормализованные цифры E.164 (без +), когда valid равен true. Когда valid равен false — только цифры из вашего ввода.
Boolean
true, когда номер структурно валиден. Это не проверка статуса линии или абонента.
Boolean
Мягкая проверка длины. true, если длина и цифры могут принадлежать реальному номеру, даже при valid: false.
String
Присутствует при valid: false. Одно из: not_a_number, possible, possible_local_only, invalid_country_code, too_short, invalid_length, too_long, unknown. Не возвращается при valid: true.
Object
Форматы international и local. Пустые строки, когда valid равен false.
String
Формат E.164 с ведущим +. Пусто, когда valid равен false.
String
Национальный формат для определённого региона. Пусто, когда valid равен false.
Object
Определённая страна/территория. Пустые поля, когда valid равен false.
String
Двухбуквенный ISO 3166-1 alpha-2 код для определённого региона.
String
Английское отображаемое имя для country.code.
String
Международный телефонный код (например, +1).
String
Подсказка по местоположению (регион, штат/провинция или город). Часто пусто за пределами US/CA. Пусто, когда valid равен false.
String
Тип линии, когда valid равен true: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special или Unknown. Всегда Unknown, когда valid равен false.
String
Название оператора, если доступно (чаще всего US/CA). Иначе пустая строка, в том числе когда valid равен false.
String
Безопасное имя оператора для отображения пользователю (когда номер валиден и регион без переносимости номеров). Пусто при valid: false или если оператора нельзя показать безопасно.
Array
Идентификаторы часовых поясов (например, America/New_York). Пустой массив при valid: true, если маппинг отсутствует; null при valid: false.
Boolean
Связан ли номер с географическим регионом. Всегда false при valid: false.
Boolean
Можно ли звонить на номер из-за пределов домашнего региона. Всегда false при valid: false.

Массовая загрузка (CSV)

Рекомендации при массовой загрузке CSV-файла:
  • Убедитесь, что в первом столбце находятся номера телефонов для анализа.
  • Удалите пустые строки из файла.
  • Включайте только один номер на строку.
  • Максимальный размер файла — 50 000 строк.

Коды ответов и ошибок

При неудачном запросе ошибка также возвращается в формате JSON с кодом и описанием — подробности ниже.

Прочее

Примечание по тарификации: каждый переданный номер телефона считается за один использованный кредит. Кредиты списываются за запрос, а не за успешный ответ. Поэтому запрос с (невалидным) номером «kasj8929hs» всё равно расходует 1 кредит.