> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cleariflow.com/llms.txt
> Use this file to discover all available pages before exploring further.
# API перевірки телефонних номерів
> Швидкий RESTful JSON API Cleariflow для структурної перевірки телефонних номерів, нормалізації E.164 та опційних даних про оператора, місцезнаходження, часовий пояс і дзвінок.
Користуватися дуже просто: передайте 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
```
https://phonevalidation.cleariflow.com/v1/
```
### Що означає `valid`
| `valid` | Значення |
| ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `true` | Номер структурно валідний для визначеного регіону. |
| `false` | Номер не вдалося розібрати або він не відповідає регіональним правилам формату. Поля `format`, `country`, `location`, `type`, `carrier`, `carrier_display`, `timezones`, `geographical` і `internationally_dialable` завжди порожні або false; `possible` і `invalid_reason` заповнюються, якщо ввід вдалося розібрати. У `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`):
```json theme={"system"}
{
"phone": "14155552671",
"valid": true,
"possible": 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": "",
"carrier_display": "",
"timezones": ["America/Los_Angeles"],
"geographical": true,
"internationally_dialable": true
}
```
**Невалідна відповідь** (`phone=123`, `country=US`):
```json theme={"system"}
{
"phone": "123",
"valid": false,
"possible": false,
"invalid_reason": "too_short",
"format": {
"international": "",
"local": ""
},
"country": {
"code": "",
"name": "",
"prefix": ""
},
"location": "",
"type": "Unknown",
"carrier": "",
"carrier_display": "",
"timezones": null,
"geographical": false,
"internationally_dialable": false
}
```
### Параметри запиту
Ваш унікальний API-ключ. У кожного користувача унікальні ключі *для кожного API Cleariflow*, тому ключ Phone Validation не працюватиме, наприклад, з API геолокації IP.
Номер телефону для перевірки.
Необов'язкова підказка ISO 3166-1 alpha-2 для національних номерів без ведучого `+`. Наприклад, `country=US` допомагає розібрати `4155552671`. Номери з міжнародним префіксом розбираються за кодом країни; визначений `country.code` у відповіді може відрізнятися від цієї підказки (наприклад, `GG` для деяких мобільних діапазонів `+44`).
### Параметри відповіді
Відповідь API повертається в універсальному легкому форматі [JSON](https://www.json.org/json-en.html).
Нормалізовані цифри E.164 (без `+`), коли `valid` дорівнює true. Коли `valid` дорівнює false — лише цифри з вашого вводу.
`true`, коли номер структурно валідний. Це **не** перевірка статусу лінії або абонента.
М'яка перевірка довжини (). `true`, якщо довжина й цифри можуть належати реальному номеру, навіть при `valid: false`.
Присутнє при `valid: false`. Одне з: `not_a_number`, `possible`, `possible_local_only`, `invalid_country_code`, `too_short`, `invalid_length`, `too_long`, `unknown`. Не повертається при `valid: true`.
Формати `international` і `local`. Порожні рядки, коли `valid` дорівнює false.
Формат E.164 з ведучим `+`. Порожньо, коли `valid` дорівнює false.
Національний формат для визначеного регіону. Порожньо, коли `valid` дорівнює false.
Визначена країна/територія. Порожні поля, коли `valid` дорівнює false.
Дволітерний [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) код для визначеного регіону.
Англійська відображувана назва для `country.code`.
Міжнародний [телефонний код](https://en.wikipedia.org/wiki/List_of_country_calling_codes) (наприклад, `+1`).
Підказка геокодування (регіон, штат/провінція або місто). Часто порожньо за межами US/CA. Порожньо, коли `valid` дорівнює false.
Тип лінії, коли `valid` дорівнює true: `Landline`, `Mobile`, `Landline_or_Mobile`, `Toll_Free`, `Premium`, `Paging`, `Special` або `Unknown`. Завжди `Unknown`, коли `valid` дорівнює false.
Назва оператора, якщо доступно (найчастіше US/CA). Інакше порожній рядок, зокрема коли `valid` дорівнює false.
Безпечна назва оператора для відображення користувачу (коли номер валідний і регіон без MNP). Порожньо при `valid: false` або якщо оператора не можна показати безпечно.
Ідентифікатори часових поясів IANA (наприклад, `America/New_York`). Порожній масив при `valid: true`, якщо мапінгу немає; `null` при `valid: false`.
Чи пов'язаний номер із географічним регіоном. Завжди `false` при `valid: false`.
Чи можна телефонувати на номер з-за меж домашнього регіону. Завжди `false` при `valid: false`.
## Масове завантаження (CSV)
Рекомендації при масовому завантаженні CSV-файлу:
* Переконайтеся, що в першому стовпці знаходяться номери телефонів для аналізу.
* Видаліть порожні рядки з файлу.
* Включайте лише один номер на рядок.
* Максимальний розмір файлу — 50 000 рядків.
## Коди відповідей і помилок
Якщо запит не вдався, помилка також повертається у форматі JSON з кодом і описом — деталі нижче.
| Code | Type | Details |
| ---- | --------------------- | ------------------------------------------------------------------------------------------------------------- |
| 200 | OK | Усе пройшло як очікувалося. |
| 400 | Bad request | Некоректний запит. |
| 401 | Unauthorized | Запит не прийнято. Зазвичай через відсутній або невірний API-ключ. |
| 422 | Quota reached | Запит перервано через нестачу API-кредитів. (Безкоштовні тарифи) |
| 429 | Too many requests | Запит перервано через досягнення ліміту запитів на секунду. На безкоштовних тарифах — до 1 запиту на секунду. |
| 500 | Internal server error | Запит не виконано через помилку на стороні сервера. |
| 503 | Service unavailable | Сервер був недоступний. |
## Інше
Примітка щодо тарифікації: кожен переданий номер телефону враховується як один використаний кредит. Кредити списуються за запит, а не за успішну відповідь. Тому запит з (невалідним) номером «kasj8929hs» все одно витрачає 1 кредит.