Проверка
API проверки телефонных номеров
Быстрый RESTful JSON API Cleariflow для структурной проверки телефонных номеров, нормализации E.164 и опциональных данных об операторе, местоположении, часовом поясе и дозвоне.
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 кредит.API проверки телефонных номеров