> ## 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` означает, что номер соответствует региональным правилам формата (длина, префикс, синтаксис). Это **не** подтверждает, что линия активна, назначена абоненту или доступна для связи. Для проверки статуса линии в реальном времени нужен отдельный 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.
Безопасное имя оператора для отображения пользователю (когда номер валиден и регион без переносимости номеров). Пусто при `valid: false` или если оператора нельзя показать безопасно.
Идентификаторы часовых поясов (например, `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 кредит.