Перейти до основного вмісту
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 кредит.