Узнать имя звонящего

Получите доступное имя звонящего для телефонного номера. Запрос выполняется в рабочей среде и может привести к списанию средств с вашей учётной записи, в том числе если результат получен из кеша сервиса. Он не изменяет имя, отображаемое при исходящих вызовах с принадлежащего вам номера.

Возвращённое имя не подтверждает личность, право владения номером или разрешение на звонок. Имя может отсутствовать, быть устаревшим или сокращённым; вместо него может возвращаться географическое обозначение или сам телефонный номер.

Запрос

Используйте активированную учётную запись API с разрешённого для неё исходного IP-адреса. Храните учётные данные в серверном хранилище секретов. В примере используются переменные окружения и вымышленный североамериканский номер; не размещайте учётные данные в URL-адресах или общедоступном коде, выполняемом в браузере.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  https://api.multitel.net/v3/cnam/12025550123

Передавайте полный номер цифрами, включая код страны: например, для Северной Америки это одиннадцать цифр, начинающихся с 1. Не рассчитывайте, что обработчик нормализует знаки пунктуации или знак плюса. Тело запроса и выбор региона не требуются. Уточните у MultiTEL поддерживаемое покрытие для вашего предполагаемого использования.

Ответ

Значения приведены только для примера; указанная стоимость не является ценовым предложением.

{
  "status": {
    "code": 200,
    "msg": ""
  },
  "response": {
    "number": "12025550123",
    "name": "EXAMPLE NAME",
    "cost": 0.0037,
    "balance": 9.9963
  }
}

Поля результата поиска имени звонящего
Поле	Значение
number	Номер, указанный в запросе.
name	Доступное имя или текст, подставляемый вместо него. Это не подтверждение личности.
cost	Настроенная для учётной записи или сервиса стоимость поиска, которую возвращает этот путь выполнения. Ориентируйтесь на текущий тариф учётной записи, а не на значение из примера.
balance	Баланс, рассчитанный для ответа. Это не результат нового транзакционного запроса баланса учётной записи.

Списания и сверка

Результаты с именем оплачиваются по тарифу CNAM, настроенному для учётной записи. Повторный запрос или получение результата из кеша могут привести к ещё одному списанию; ключ идемпотентности не предоставляется. Проверьте текущий тариф учётной записи, прежде чем включать автоматические запросы.

Для пустого имени в кеше известно ограничение ответа: обработчик может вернуть код API 200 с пустым именем, ненулевой стоимостью и уменьшенным расчётным балансом, хотя в этой ветке выполнения средства с учётной записи не списываются. Не считайте такой ответ сам по себе доказательством списания. Сверьте данные с записями о начислениях и списаниях по учётной записи и выполните новый запрос баланса, а при неоднозначных результатах обратитесь в службу поддержки.

В настоящее время проверка предоплаченных средств требует наличия на балансе не менее 0.004 до выполнения поиска, независимо от настроенной стоимости одного запроса. Запросы от учётной записи с отключёнными покупками также отклоняются. Эти проверки не делают данную конечную точку API для получения ценовых предложений или ограничения расходов.

Ошибки и повторные попытки

Проверяйте как статус HTTP, так и status.code/status.msg в JSON. Код API 403 может означать недостаток предоплаченных средств, запрет покупок, проблему с авторизацией учётной записи или отсутствие найденного имени звонящего. В ветке, где имя не найдено, код может возвращаться строкой. Изучайте сообщение, а не считайте каждый код 403 признаком неверных учётных данных. При конфликтах конфигурации может возвращаться код API 500.

Время ожидания может истечь уже после выполнения платного поиска. Используйте ограниченное число повторных попыток с увеличением интервала между ними только тогда, когда это подходит вашему приложению, и сначала сверяйте попытки с неопределённым результатом. Не повторяйте многократно запрос для отклонённого номера или после отказа из-за прав учётной записи либо баланса. Кеширование ответов в вашем приложении может сократить число повторных запросов при соблюдении условий вашего соглашения и требований к точности.

Другие операции с номерами

Эта операция чтения выполняется отдельно от изменения имени для исходящих вызовов/данных LIDB, размещения записи в справочнике или регистрации звонящего. Для этих операций предусмотрены собственные обязательные поля, требования к авторизации и сборы. Используйте проверку покрытия выделения номеров для проверки по таблице префиксов или поиск номеров для просмотра номеров, доступных для заказа. Ни одна из этих операций не подтверждает, что звонящий является тем, за кого себя выдаёт.