Skip to main content
GET
API перевірки телефонних номерів
Користуватися дуже просто: передайте API-ключ і номер телефону. API поверне, чи є номер структурно валідним, а для валідного номера — нормалізовані формати E.164 і додаткові метадані: тип лінії, підказки геокодування, дані оператора, часові пояси та ознаки дзвінка, якщо доступні.
valid: true означає, що номер відповідає регіональним правилам формату (довжина, префікс, синтаксис). Це не підтверджує, що лінія активна, призначена абоненту або доступна для зв’язку. Для перевірки статусу лінії в реальному часі потрібен carrier 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
Безпечна назва оператора для відображення користувачу (коли номер валідний і регіон без MNP). Порожньо при valid: false або якщо оператора не можна показати безпечно.
Array
Ідентифікатори часових поясів IANA (наприклад, America/New_York). Порожній масив при valid: true, якщо мапінгу немає; null при valid: false.
Boolean
Чи пов’язаний номер із географічним регіоном. Завжди false при valid: false.
Boolean
Чи можна телефонувати на номер з-за меж домашнього регіону. Завжди false при valid: false.

Масове завантаження (CSV)

Рекомендації при масовому завантаженні CSV-файлу:
  • Переконайтеся, що в першому стовпці знаходяться номери телефонів для аналізу.
  • Видаліть порожні рядки з файлу.
  • Включайте лише один номер на рядок.
  • Максимальний розмір файлу — 50 000 рядків.

Коди відповідей і помилок

Якщо запит не вдався, помилка також повертається у форматі JSON з кодом і описом — деталі нижче.

Інше

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