Перейти к основному содержанию
GET
/
v1
API проверки телефонных номеров
curl --request GET \
  --url https://phonevalidation.cleariflow.com/v1
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
Использовать очень просто: передайте API-ключ и номер телефона. API вернёт, является ли номер структурно валидным (по Google libphonenumber), а при валидном номере — нормализованные форматы E.164 и дополнительные метаданные: тип линии, подсказки геокодирования и данные оператора, если доступны.
valid: true означает, что номер соответствует региональным правилам формата (длина, префикс, синтаксис). Это не подтверждает, что линия активна, назначена абоненту или доступна для связи. Для проверки статуса линии в реальном времени нужен HLR/SMS 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

https://phonevalidation.cleariflow.com/v1/

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

validЗначение
trueНомер структурно валиден для определённого региона (libphonenumber IsValidNumber).
falseНомер не удалось разобрать или он не соответствует региональным правилам формата. Поля format, country, location, type и carrier всегда пустые; в phone только цифры из вашего ввода.
Вымышленные американские номера 555 и другие структурно валидные, но не назначенные диапазоны могут по-прежнему возвращать valid: true. Поля carrier и location заполняются в основном из метаданных US/CA и часто пусты для других регионов.

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

API требует ваш уникальный API-ключ и номер телефона для проверки: 
https://phonevalidation.cleariflow.com/v1/
? api_key = YOUR_UNIQUE_API_KEY
& phone = 14155552671
& country = US
Валидный ответ (phone=14155552671, country=US): 
{
  "phone": "14155552671",
  "valid": true,
  "format": {
    "international": "+14155552671",
    "local": "(415) 555-2671"
  },
  "country": {
    "code": "US",
    "name": "United States",
    "prefix": "+1"
  },
  "location": "San Francisco, CA",
  "type": "Landline_or_Mobile",
  "carrier": ""
}
Невалидный ответ (phone=123, country=US): 
{
  "phone": "123",
  "valid": false,
  "format": {
    "international": "",
    "local": ""
  },
  "country": {
    "code": "",
    "name": "",
    "prefix": ""
  },
  "location": "",
  "type": "Unknown",
  "carrier": ""
}

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

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

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

Ответ API возвращается в универсальном лёгком формате JSON.
​
phone
String
Нормализованные цифры E.164 (без +), когда valid равен true. Когда valid равен false — только цифры из вашего ввода.
​
valid
Boolean
true, когда номер структурно валиден по libphonenumber. Это не проверка статуса линии или абонента.
​
format
Object
Форматы international и local. Пустые строки, когда valid равен false.
​
format.international
String
Формат E.164 с ведущим +. Пусто, когда valid равен false.
​
format.local
String
Национальный формат для определённого региона. Пусто, когда valid равен false.
​
country
Object
Определённая страна/территория. Пустые поля, когда valid равен false.
​
country.code
String
Двухбуквенный ISO 3166-1 alpha-2 код для определённого региона.
​
country.name
String
Английское отображаемое имя для country.code.
​
country.prefix
String
Международный телефонный код (например, +1).
​
location
String
Подсказка геокодирования из метаданных libphonenumber (регион, штат/провинция или город). Часто пусто за пределами US/CA. Пусто, когда valid равен false.
​
type
String
Тип линии, когда valid равен true: Landline, Mobile, Landline_or_Mobile, Toll_Free, Premium, Paging, Special или Unknown. Всегда Unknown, когда valid равен false.
​
carrier
String
Название оператора из метаданных libphonenumber, если доступно (чаще всего US/CA). Иначе пустая строка, в том числе когда valid равен false.

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

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

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

При неудачном запросе ошибка также возвращается в формате JSON с кодом и описанием — подробности ниже.
CodeTypeDetails
200OKВсё прошло как ожидалось.
400Bad requestНекорректный запрос.
401UnauthorizedЗапрос не принят. Обычно из-за отсутствующего или неверного API-ключа.
422Quota reachedЗапрос прерван из-за недостатка API-кредитов. (Бесплатные тарифы)
429Too many requestsЗапрос прерван из-за достижения лимита запросов в секунду. На бесплатных тарифах — до 1 запроса в секунду.
500Internal server errorЗапрос не выполнен из-за ошибки на стороне сервера.
503Service unavailableСервер был недоступен.

​
Прочее

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