Початок роботи

Глобальна інфраструктура мобільного зв'язку функціонує на основі системи, відомої як сигнальна мережа SS7. Ця мережа забезпечує обмін даними абонентів, маршрутизацію викликів, передачу SMS та оновлення статусу мобільного з'єднання в реальному часі між операторами. Кожна мобільна мережа підтримує реєстр домашнього розташування (HLR) - основну базу даних, яка зберігає важливу інформацію про своїх абонентів.

Технологія HLR Lookup дозволяє компаніям запитувати ці реєстри та отримувати актуальні дані про підключення та мережу для будь-якого номера мобільного телефону. Це включає інформацію про те, чи увімкнений телефон, до якої мережі він зараз підключений, чи був номер перенесений, чи є номер дійсним або деактивованим, а також чи знаходиться він у роумінгу.

API HLR Lookups надає безперебійний доступ до цих даних у реальному часі, дозволяючи компаніям перевіряти мобільні номери, оптимізувати маршрутизацію та покращувати комунікації з клієнтами. Ця документація допоможе вам інтегрувати HLR Lookups у ваше програмне забезпечення, забезпечуючи автоматизоване отримання мобільних даних у реальному часі.

Використання API HLR Lookups

Виконання запитів HLR Lookup є швидким, безпечним та простим. Після реєстрації та отримання вашого API-ключа, ви можете авторизуватися та ініціювати миттєві запити за допомогою простих HTTP POST запитів через POST /hlr-lookup. Також ви можете обробляти великі обсяги даних, обравши швидкі асинхронні API-запити з отриманням результатів на ваш сервер через webhook, як пояснюється в розділі концепції.

Приклад запиту

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -H "X-Digest-Key: YOUR_API_KEY" \
          -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
          -H "X-Digest-Timestamp: UNIX_TIMESTAMP" \
          -d "@payload.json"

Автентифікація передається через HTTP-заголовки, а payload.json повинен (як мінімум) містити наступний JSON-об'єкт:

Приклад payload

{
   "msisdn": "+14156226819"
}

Після успішного виконання ви отримаєте відповідь з даними про підключення в реальному часі для вказаного мобільного номера.

Успішна відповідь application/json

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

Для повного опису атрибутів запиту та відповіді, а також статусів підключення, див. POST /hlr-lookup.

Додаткові сервіси перевірки

Перевірка переносимості мобільних номерів (MNP)

Використовуйте MNP-запити для визначення належності до мережі та деталей переносимості без запиту даних про підключення в реальному часі. Якщо вам потрібен лише MCCMNC номера, зверніться до POST /mnp-lookup.

Визначення типу номера (NT)

Визначте, чи належить телефонний номер до стаціонарної лінії, мобільного, преміум-тарифу, VoIP, пейджера або інших діапазонів нумерації за допомогою POST /nt-lookup.

Комплекти розробки програмного забезпечення (SDK)

API HLR Lookups працює з будь-яким REST-клієнтом на будь-якій мові програмування, і ми опублікували SDK для PHP, Ruby та NodeJS на нашому GitHub, щоб допомогти вам швидко розпочати роботу.

Інструменти

Для забезпечення безперебійної розробки ми пропонуємо повний набір інструментів, включаючи моніторинг API-запитів та webhook у браузері, білий список IP-адрес, надійні опції автентифікації та тестову точку доступу для автентифікації.

Не розробник?

HLR Lookups та запити переносимості номерів можна виконувати без програмування. Дізнайтеся більше про наш корпоративний веб-клієнт та функції звітності у браузері.

Автентифікація

Для забезпечення безпеки та належного контролю доступу більшість запитів до HLR Lookups API вимагають автентифікації. Ендпоінти поділяються на публічні та захищені. При доступі до захищеного ендпоінту ваш запит має бути автентифікований за допомогою API-ключа та секрету через метод Digest-Auth або Basic-Auth. Digest-Auth є більш безпечним варіантом і настійно рекомендується. Використовуйте ендпоінт GET /auth-test для перевірки налаштувань автентифікації.

API-ключ та API-секрет

Отримайте ваш API-ключ та секрет на сторінці налаштувань API. Ви також можете налаштувати бажаний метод автентифікації та увімкнути білий список IP-адрес для підвищення безпеки. Якщо ви підозрюєте, що ваш API-секрет було скомпрометовано, ви можете згенерувати новий у будь-який час.

Basic Auth Digest Auth Білий список IP

Стандартна базова автентифікація проста у впровадженні та широко підтримується. Ви можете автентифікуватися, передаючи свій API-ключ та секрет як пару user:pass у HTTP-запиті.

HTTP Basic Auth

curl 'https://YOUR_API_KEY:YOUR_API_SECRET@www.hlr-lookups.com/api/v2/auth-test'

Це надсилає заголовок Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Рекомендовано: X-Basic заголовок з SHA256

Для підвищення безпеки ви можете надіслати SHA256-хеш ваших облікових даних замість їх прямої передачі у форматі base64. Щоб використовувати цей метод, обчисліть хеш вашої пари YOUR_API_KEY:YOUR_API_SECRET та надішліть його через заголовок X-Basic:

Запит Basic Auth

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: BASIC_AUTH_HASH"

Заголовки базової автентифікації

Ключ	Тип	Опис
`X-Basic`	string	SHA256-хеш `YOUR_API_KEY:YOUR_API_SECRET`. Включіть символ двокрапки (:) у хеш.	обов'язковий

Приклад коду

$key = 'YOUR_API_KEY';
$secret = 'YOUR_API_SECRET';

$basicAuthHash = hash('sha256', $key . ':' . $secret);

Digest-Auth є рекомендованим методом для забезпечення доступу до захищених ендпоінтів HLR Lookup API. Кожен запит має включати наступні заголовки: X-Digest-Key, X-Digest-Signature та X-Digest-Timestamp, які пояснюються нижче.

Приклад запиту

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Заголовки запиту

Ключ	Тип	Опис
`X-Digest-Key`	string	Ваш унікальний API-ключ HLR Lookups.	обов'язковий
`X-Digest-Signature`	string	Унікальний підпис автентифікації (див. нижче).	обов'язковий
`X-Digest-Timestamp`	integer	Поточна мітка часу Unix (також див. `GET /time`).	обов'язковий

Формування підпису

X-Digest-Signature створюється за допомогою SHA256 HMAC-хешу з вашим API-секретом як спільним ключем.

Рядок для хешування структурований наступним чином:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Символ . означає конкатенацію рядків.

Компоненти Digest-підпису

Компонент	Тип	Опис
`ENDPOINT_PATH`	string	Запитуваний API-ендпоінт, наприклад, `/auth-test` у нижньому регістрі.
`UNIX_TIMESTAMP`	integer	Поточна мітка часу Unix (має бути в межах 30 секунд). Див. `GET /time`.
`REQUEST_METHOD`	string	Використовуваний HTTP-метод, наприклад, `POST` або `GET`.
`REQUEST_BODY`	string	Дані тіла запиту. Встановіть `null` для `GET` запитів.

Приклади коду

PHP

NodeJS

Ruby

$path = '/auth-test'
    $timestamp = time();
    $method = 'GET';
    $body = $method == 'GET' ? null : json_encode($params);
    $secret = 'YOUR_API_SECRET';

    $signature = hash_hmac('sha256', $path . $timestamp . $method . $body, $secret);

require('crypto');

    let path = '/auth-test'
    let timestamp = Date.now() / 1000 | 0;
    let method = 'GET'
    let body = method === 'GET' ? '' : JSON.stringify(params)
    let secret = 'YOUR_API_SECRET'

    let signature = crypto.createHmac('sha256', secret)
                    .update(path + timestamp + method + body)
                    .digest('hex');

require 'openssl'

path = '/auth-test'
timestamp = Time.now.to_i
method = 'GET'
body = method == 'GET' ? NIL : params.to_json
secret = 'YOUR_API_SECRET'

signature = OpenSSL::HMAC.hexdigest('sha256', secret, path + timestamp.to_s + method + body.to_s)

Прокрутити вгору

Концепції

Впровадження HLR-запитів у будь-якій мові програмування або системі через наш HTTP REST API є простим та ефективним. Завдяки простому процесу інтеграції ви можете розпочати запити до мобільних мереж у реальному часі для миттєвого отримання інформації про дійсність телефонних номерів, статус підключення та деталі маршрутизації.

Вибір відповідного API залежить від вашого конкретного випадку використання. Якщо вам потрібні результати запитів у реальному часі для таких застосунків, як VoIP-телефонія, виявлення шахрайства або маршрутизація SMS, синхронний API є найкращим вибором. Однак, якщо ваш випадок використання передбачає високообсягову обробку, масові запити або перевірку даних у великих масштабах, асинхронний API пропонує оптимізовану продуктивність із ефективністю пропускної здатності та можливостями пакетних запитів.

Налаштуйте API для використання одного з наших спеціальних варіантів маршрутизації для оптимізації швидкості, точності та економічної ефективності. Ви також можете зберігати результати запитів у сховищах для зручного завантаження звітів у форматах CSV і JSON, а також для розширеної аналітики через веб-інтерфейс.

Синхронний API HLR-запитів

Кінцева точка POST /hlr-lookup обробляє один номер мобільного телефону (MSISDN) на запит і миттєво повертає результати в тілі HTTP-відповіді. Результати форматуються як JSON і ідеально підходять для застосунків реального часу, включаючи перевірку мобільних номерів, маршрутизацію дзвінків та доставку SMS-повідомлень.

Синхронний виклик API складається з прямого HTTP-запиту та відповіді. Ваша система надсилає один MSISDN (мобільний номер) на запит і отримує миттєву відповідь, що містить результати HLR-запиту в реальному часі у форматі JSON. Цей API оптимізовано для випадків використання, що вимагають миттєвої перевірки та контролю підключення, таких як виявлення шахрайства, маршрутизація VoIP-дзвінків та оптимізація SMS-шлюзів.

Асинхронний API HLR-запитів

Кінцева точка POST /hlr-lookups призначена для масової та високообсягової обробки, дозволяючи надсилати до 1,000 MSISDN на запит. Замість миттєвого повернення результатів, цей API використовує автоматизовані вебхуки для поступового надсилання результатів на ваш сервер. Результати запитів повертаються як JSON-об'єкти через HTTP POST зворотні виклики.

Асинхронний API оптимізовано для швидкості, ефективності та масштабованості. Він усуває проблеми мережевої затримки, пов'язані з синхронними викликами, що робить його ідеальним для бізнесу, який потребує високопродуктивних запитів. Ваша система надсилає до 1,000 MSISDN на запит, а наша платформа обробляє їх паралельно, повертаючи результати на ваш сервер через HTTP-вебхуки пакетами до 1,000 результатів на зворотний виклик.

SDK (комплекти для розробки програмного забезпечення)

Наші комплекти для розробки програмного забезпечення (SDK) для PHP, NodeJS та Ruby спрощують процес інтеграції, дозволяючи вам ефективно та з мінімальними зусиллями підключитися до API HLR Lookups.

Ці SDK надають готові функції, обробку автентифікації та структуровані шаблони API-запитів, скорочуючи час розробки та забезпечуючи дотримання найкращих практик.

Ознайомтеся з повним переліком доступних SDK на GitHub та почніть інтеграцію вже сьогодні.

PHP

NodeJS

Ruby

1   include('HLRLookupClient.class.php');
2
3   $client = new HLRLookupClient(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   );
8
9   $params = array('msisdn' => '+14156226819');
10  $response = $client->post('/hlr-lookup', $params);

Переглянути на GitHub README.md

1   require('node-hlr-client');
2
3   let response = await client.post('/hlr-lookup', {msisdn: '+491788735000'});
4
5   if (response.status === 200) {
6      // lookup was successful
7      let data = response.data;
8   }

Переглянути на GitHub README.md

1   require 'ruby_hlr_client/client'
2
3   client = HlrLookupsSDK::Client.new(
4       'YOUR-API-KEY',
5       'YOUR-API-SECRET',
6       '/var/log/hlr-lookups.log'
7   )
8
9   params = { :msisdn => '+14156226819' }
10  response = client.get('/hlr-lookup', params)

Переглянути на GitHub README.md

Прокрутити вгору

POST/hlr-lookupзахищено

Виконує синхронний HLR-запит, надаючи дані про з'єднання та портативність мобільних номерів у реальному часі безпосередньо від мережевих операторів. Цей ендпоінт ідеально підходить для сценаріїв обробки трафіку в реальному часі, коли програмам потрібна негайна перевірка доступності телефонного номера (підключений) або його недоступності (вимкнений). Крім того, він допомагає відрізнити активні номери від недійсних, невідомих або фальшивих.

Для масової обробки великих обсягів даних, які не потребують миттєвих результатів, розгляньте використання асинхронного POST /hlr-lookups, який оптимізовано для високошвидкісної пакетної обробки.

Якщо ваша основна мета - отримання даних про портативність мобільних номерів (MCCMNC) і вам не потрібен статус з'єднання в реальному часі, POST /mnp-lookup пропонує економічно ефективну альтернативу для запитів щодо портативності мобільних номерів.

Запит Успішна відповідь Відповідь з помилкою Довідник статусів

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookup' \
          -d "@payload.json"

Дані запиту

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`msisdn`	string	Номер мобільного телефону (MSISDN) для запиту, наданий у міжнародному форматі (наприклад, +14156226819 або 0014156226819). Коди країн обов'язкові.	null	обов'язковий
`route`	string(3)	Необов'язковий тризначний ідентифікатор, що вказує маршрут для цього запиту. Встановіть значення `null` або пропустіть цей параметр, щоб застосувати ваше налаштування маршрутизації або дозволити системі автоматично визначити найкращий маршрут для цього запиту.	null	необов'язково
`storage`	string	Необов'язковий ідентифікатор сховища, що вказує звіт, де зберігатимуться результати для ручного перегляду, аналітики та звітності. Система автоматично додає позначку часу з поточним місяцем. Якщо пропущено або встановлено `null`, система автоматично групуватиме результати за місяцями для цілей звітності.	null	необов'язково

{
   "id":"f94ef092cb53",
   "msisdn":"+14156226819",
   "connectivity_status":"CONNECTED",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "imsi":"***************",
   "msin":"**********",
   "msc":"************",
   "original_network_name":"Verizon Wireless",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1",
   "is_ported":true,
   "ported_network_name":"T-Mobile US",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "is_roaming":false,
   "roaming_network_name":null,
   "roaming_country_name":null,
   "roaming_country_code":null,
   "roaming_country_prefix":null,
   "cost":"0.0100",
   "timestamp":"2020-08-07 19:16:17.676+0300",
   "storage":"SYNC-API-2020-08",
   "route":"IP1",
   "processing_status":"COMPLETED",
   "error_code":null,
   "error_description":null,
   "data_source":"LIVE_HLR",
   "routing_instruction":"STATIC:IP1"
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`id`	string(12)	Унікальний ідентифікатор, присвоєний цьому запиту на перевірку.	false
`msisdn`	string	Номер мобільного телефону, що перевіряється, у міжнародному форматі (наприклад, +14156226819 або 0014156226819).	false
`connectivity_status`	string	Вказує, чи було успішно отримано статус підключення номера. Можливі значення: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` або `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	П'яти- або шестизначний код мобільної країни (MCC) та код мобільної мережі (MNC), що ідентифікують мережу, з якою наразі пов'язаний номер телефону.	true
`mcc`	string(3)	Тризначний код мобільної країни (MCC), що ідентифікує країну, де зареєстровано номер телефону.	true
`mnc`	string(2\|3)	Дво- або тризначний код мобільної мережі (MNC), що ідентифікує конкретну мережу, до якої належить номер телефону.	true
`imsi`	string	Міжнародний ідентифікатор мобільного абонента (IMSI), унікальний ідентифікатор SIM-карти, пов'язаної з цим номером. Доступність залежить від конфігурації мережі.	true
`msin`	string(10)	Ідентифікаційний номер мобільної підписки (MSIN) у базі даних мобільного оператора. Доступність залежить від конфігурації мережі.	true
`msc`	string(12)	Центр комутації мобільного зв'язку (MSC), що наразі обслуговує зв'язок цього абонента. Доступність залежить від конфігурації мережі.	true
`original_network_name`	string	Назва оригінального (рідного) оператора мережі, пов'язаного з цим номером.	true
`original_country_name`	string	Повна назва країни, де було спочатку зареєстровано номер мобільного телефону, англійською мовою.	true
`original_country_code`	string(2)	Двосимвольний код країни ISO, що представляє країну, де було вперше присвоєно номер телефону.	true
`original_country_prefix`	string	Міжнародний телефонний код (код виклику країни), що відповідає оригінальній країні номера мобільного телефону.	true
`is_ported`	boolean	Вказує, чи було перенесено мобільний номер з його оригінальної мережі до іншого оператора.	true
`ported_network_name`	string	Назва оператора мережі, до якого було перенесено мобільний номер, якщо застосовно.	true
`ported_country_name`	string	Назва країни, до якої було перенесено мобільний номер, якщо застосовно.	true
`ported_country_code`	string(2)	Двосимвольний код країни ISO, що представляє країну, до якої було перенесено мобільний номер, якщо застосовно.	true
`ported_country_prefix`	string	Міжнародний телефонний код (код виклику країни) для країни, до якої було перенесено мобільний номер, якщо застосовно.	true
`is_roaming`	boolean	Вказує, чи перебуває мобільний номер наразі в роумінгу в іноземній мережі. Доступність інформації про роумінг залежить від оператора мобільного зв'язку.	true
`roaming_network_name`	string	Назва мережі, в якій мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`roaming_country_name`	string	Назва країни, де мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`roaming_country_code`	string(2)	Двосимвольний код країни ISO країни, де мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`roaming_country_prefix`	string	Міжнародний телефонний код (код виклику країни) країни, де мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`cost`	string	Десяткове значення, представлене як рядок, що вказує вартість перевірки в євро.	true
`timestamp`	string	Часова мітка у форматі W3C з часовим поясом, що вказує, коли було завершено перевірку.	true
`storage`	string	Назва сховища, де було збережено результати перевірки. Це відповідає назвам звітів та завантаженням CSV, доступним через веб-інтерфейс.	true
`route`	string(3)	Трисимвольний ідентифікатор, що вказує метод маршрутизації, використаний для цього запиту на перевірку.	true
`processing_status`	string	Результат обробки перевірки. Можливі значення: `COMPLETED` (успішно), `REJECTED` (мережа недоступна, плата не стягнута) або `FAILED` (сталася помилка під час обробки).	false
`error_code`	integer	Необов'язковий внутрішній код помилки, що надає додаткову діагностичну інформацію для служби підтримки клієнтів.	true
`error_description`	string	Коротке пояснення наданого коду помилки (якщо є) простим текстом англійською мовою.	true
`data_source`	string	Джерело даних, використане для цього запиту. Можливі значення: `LIVE_HLR` (запит HLR у реальному часі) або `MNP_DB` (статична база даних переносимості мобільних номерів). Див. опції маршрутизації для деталей.	false
`routing_instruction`	string	Рядок, розділений двокрапками, що описує інструкцію маршрутизації, використану в запиті. Перший компонент - `STATIC`, коли ви вказали маршрут, або `AUTO` для автоматичної маршрутизації; другий компонент - ідентифікатор маршруту, а для запитів з автоматичною маршрутизацією третій компонент показує джерело, на основі якого прийнято рішення про маршрутизацію (тобто `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Статус	Опис
CONNECTED	Номер дійсний, і цільовий пристрій наразі підключений до мобільної мережі. Дзвінки, SMS та інші послуги мають успішно досягти одержувача.
ABSENT	Номер дійсний, але цільовий пристрій або вимкнений, або тимчасово поза зоною покриття мережі. Повідомлення або дзвінки можуть не бути доставлені до моменту повторного підключення пристрою до мережі.
INVALID_MSISDN	Номер недійсний або наразі не призначений жодному абоненту в мобільній мережі. Дзвінки та повідомлення на цей номер не будуть доставлені.
UNDETERMINED	Не вдалося визначити статус підключення номера. Це може бути спричинено недійсним номером, помилкою SS7 або відсутністю зв'язку з цільовим оператором мережі. Перевірте код помилки та його опис для додаткової діагностики.

Прокрутити вгору

POST/hlr-lookupsзахищено

Ініціює пакет асинхронних HLR-запитів, отримуючи актуальні дані про підключення мобільних телефонів та їх портованість від мережевих операторів. Результати надсилаються через вебхуки на ваш сервер. Цей метод оптимізовано для обробки великих обсягів номерів, які не потребують миттєвої відповіді, наприклад для очищення та перевірки баз даних. Для додатків реального часу, таких як маршрутизація дзвінків або доставка SMS, розгляньте використання ендпоінту POST /hlr-lookup.

Цей ендпоінт ідеально підходить для масової обробки, коли мета - визначити телефонні номери, які наразі доступні (підключені) або недоступні (телефон вимкнено), відфільтрувавши недійсні, непризначені або фальшиві номери. Крім того, він надає актуальний статус портованості (MCCMNC) разом з деталями підключення.

Перед використанням цього ендпоінту переконайтеся, що налаштовано URL вебхука для асинхронного отримання результатів запитів. Ви можете налаштувати це у ваших налаштуваннях API.

Запит Успішна відповідь Відповідь з помилкою Вебхуки Довідник статусів

curl -X POST 'https://www.hlr-lookups.com/api/v2/hlr-lookups' \
          -d "@payload.json"

Дані запиту

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`msisdns`	array	Масив номерів мобільних телефонів (MSISDN) у міжнародному форматі (наприклад, +14156226819 або 0014156226819). Ви можете включити до 1000 номерів на запит.	null	обов'язковий
`route`	string(3)	Необов'язковий тризначний ідентифікатор, що вказує маршрут для цього запиту. Встановіть значення `null` або пропустіть цей параметр, щоб застосувати ваше налаштування маршрутизації або дозволити системі автоматично визначити найкращий маршрут для цього запиту.	null	необов'язково
`storage`	string	Необов'язковий ідентифікатор сховища, що вказує звіт, де зберігатимуться результати для ручного перегляду, аналітики та звітності. Система автоматично додає позначку часу з поточним місяцем. Якщо пропущено або встановлено `null`, система автоматично групуватиме результати за місяцями для цілей звітності.	null	необов'язково

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`accepted`	array	Список об'єктів, що містять унікальні ідентифікатори та MSISDN, які прийняті до обробки.	false
`accepted_count`	integer	Загальна кількість MSISDN, успішно прийнятих до обробки.	false
`rejected`	array	Список об'єктів, що містять унікальні ідентифікатори та MSISDN, які відхилені від обробки, зазвичай через недійсні номери. Відхилені записи не тарифікуються.	false
`rejected_count`	integer	Загальна кількість MSISDN, відхилених через помилки валідації.	false
`total_count`	integer	Загальна кількість прийнятих та відхилених MSISDN, які були подані на обробку.	false
`cost`	string	Десяткове значення, представлене як рядок, що вказує загальну вартість у євро для прийнятих запитів.	false
`storage`	string	Назва сховища, куди додаються результати запитів, використовується для звітності та завантаження CSV через веб-інтерфейс.	false
`route`	string(3\|4)	Триабо чотирисимвольний ідентифікатор, що вказує маршрут, використаний для цього запиту. Містить AUTO, якщо було запитано автоматичну маршрутизацію на основі номера.	false
`webhook_urls`	array	URL-адреси вебхуків, налаштовані у ваших налаштуваннях API. Результати надсилаються сюди.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Обробка вебхуків

Після надсилання наша платформа починає обробку наданих номерів телефонів і надсилає результати на попередньо вказану URL-адресу вебхука на вашому сервері. Результати передаються як HTTP POST запит з JSON-об'єктом у тілі запиту.

Автентифікація

Автентифікуйте вебхук, перевіривши HTTP-заголовок X-Signatures.

Заголовок X-Signatures містить список підписів, розділених крапкою з комою. Кожен підпис у списку генерується за допомогою одного з API-секретів, налаштованих у вашому обліковому записі. Щоб перевірити вебхук, згенеруйте SHA-256 хеш, використовуючи ваш API-ключ, секрет і необроблене тіло HTTP - потім порівняйте його з підписами у списку.

Збіг підтверджує, що запит автентичний і підписаний секретом, яким ви керуєте.

Приклад коду

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

Запит є дійсним, якщо будь-який із підписів, наданих у заголовку, дорівнює SHA256 хешу, обчисленому для об'єднаного рядка вашого API-ключа, секрету та тіла HTTP.

Підтвердження отримання

Очікується, що ваш сервер відповість HTTP-кодом статусу 200 OK для підтвердження успішного отримання. Якщо повертається будь-який інший код відповіді, виникає тайм-аут (10 секунд) або виникає будь-яка інша проблема з доставкою, система автоматично повторить спробу надсилання вебхука через одну хвилину. Якщо запит продовжує завершуватися невдачею, повторні спроби виконуватимуться за стратегією експоненційної затримки з наступними спробами через 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 хвилин.

Цей механізм повторних спроб забезпечує максимальну надійність доставки результатів перевірок до вашої інфраструктури. Це мінімізує ризик втрати даних через тимчасові проблеми з мережею або недоступність сервера.

Дані вебхука

{
   "type":"HLR",
   "results":[
      {
         "id":"3b4ac4b6ed1b",
         "msisdn":"+905536939460",
         "connectivity_status":"CONNECTED",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "imsi":"28603XXXXXXXXXX",
         "msin":"XXXXXXXXXX",
         "msc":"XXXXXXXXXX",
         "original_network_name":"Turk Telekom (AVEA)",
         "original_country_name":"Turkey",
         "original_country_code":"TR",
         "original_country_prefix":"+90",
         "is_ported":false,
         "ported_network_name":null,
         "ported_country_name":null,
         "ported_country_code":null,
         "ported_country_prefix":null,
         "is_roaming":false,
         "roaming_network_name":null,
         "roaming_country_name":null,
         "roaming_country_code":null,
         "roaming_country_prefix":null,
         "cost":"0.0100",
         "timestamp":"2020-08-13 00:04:38.261+0300",
         "storage":"ASYNC-API-2020-08",
         "route":"IP1",
         "processing_status":"COMPLETED",
         "error_code":null,
         "error_description":null,
         "data_source":"LIVE_HLR",
         "routing_instruction":"STATIC:IP1"
      }
   ]
}

Атрибути payload вебхука

Об'єкт JSON містить атрибут type => HLR разом з атрибутом results, який включає список об'єктів запитів, як задокументовано нижче.

Ім'я	Тип	Опис	Необов'язковий
`id`	string(12)	Унікальний ідентифікатор, присвоєний цьому запиту на перевірку.	false
`msisdn`	string	Номер мобільного телефону, що перевіряється, у міжнародному форматі (наприклад, +14156226819 або 0014156226819).	false
`connectivity_status`	string	Вказує, чи було успішно отримано статус підключення номера. Можливі значення: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` або `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	П'яти- або шестизначний код мобільної країни (MCC) та код мобільної мережі (MNC), що ідентифікують мережу, з якою наразі пов'язаний номер телефону.	true
`mcc`	string(3)	Тризначний код мобільної країни (MCC), що ідентифікує країну, де зареєстровано номер телефону.	true
`mnc`	string(2\|3)	Дво- або тризначний код мобільної мережі (MNC), що ідентифікує конкретну мережу, до якої належить номер телефону.	true
`imsi`	string	Міжнародний ідентифікатор мобільного абонента (IMSI), унікальний ідентифікатор SIM-карти, пов'язаної з цим номером. Доступність залежить від конфігурації мережі.	true
`msin`	string(10)	Ідентифікаційний номер мобільної підписки (MSIN) у базі даних мобільного оператора. Доступність залежить від конфігурації мережі.	true
`msc`	string(12)	Центр комутації мобільного зв'язку (MSC), що наразі обслуговує зв'язок цього абонента. Доступність залежить від конфігурації мережі.	true
`original_network_name`	string	Назва оригінального (рідного) оператора мережі, пов'язаного з цим номером.	true
`original_country_name`	string	Повна назва країни, де було спочатку зареєстровано номер мобільного телефону, англійською мовою.	true
`original_country_code`	string(2)	Двосимвольний код країни ISO, що представляє країну, де було вперше присвоєно номер телефону.	true
`original_country_prefix`	string	Міжнародний телефонний код (код виклику країни), що відповідає оригінальній країні номера мобільного телефону.	true
`is_ported`	boolean	Вказує, чи було перенесено мобільний номер з його оригінальної мережі до іншого оператора.	true
`ported_network_name`	string	Назва оператора мережі, до якого було перенесено мобільний номер, якщо застосовно.	true
`ported_country_name`	string	Назва країни, до якої було перенесено мобільний номер, якщо застосовно.	true
`ported_country_code`	string(2)	Двосимвольний код країни ISO, що представляє країну, до якої було перенесено мобільний номер, якщо застосовно.	true
`ported_country_prefix`	string	Міжнародний телефонний код (код виклику країни) для країни, до якої було перенесено мобільний номер, якщо застосовно.	true
`is_roaming`	boolean	Вказує, чи перебуває мобільний номер наразі в роумінгу в іноземній мережі. Доступність інформації про роумінг залежить від оператора мобільного зв'язку.	true
`roaming_network_name`	string	Назва мережі, в якій мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`roaming_country_name`	string	Назва країни, де мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`roaming_country_code`	string(2)	Двосимвольний код країни ISO країни, де мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`roaming_country_prefix`	string	Міжнародний телефонний код (код виклику країни) країни, де мобільний номер наразі перебуває в роумінгу, якщо застосовно.	true
`cost`	string	Десяткове значення, представлене як рядок, що вказує вартість перевірки в євро.	true
`timestamp`	string	Часова мітка у форматі W3C з часовим поясом, що вказує, коли було завершено перевірку.	true
`storage`	string	Назва сховища, де було збережено результати перевірки. Це відповідає назвам звітів та завантаженням CSV, доступним через веб-інтерфейс.	true
`route`	string(3)	Трисимвольний ідентифікатор, що вказує метод маршрутизації, використаний для цього запиту на перевірку.	true
`processing_status`	string	Результат обробки перевірки. Можливі значення: `COMPLETED` (успішно), `REJECTED` (мережа недоступна, плата не стягнута) або `FAILED` (сталася помилка під час обробки).	false
`error_code`	integer	Необов'язковий внутрішній код помилки, що надає додаткову діагностичну інформацію для служби підтримки клієнтів.	true
`error_description`	string	Коротке пояснення наданого коду помилки (якщо є) простим текстом англійською мовою.	true
`data_source`	string	Джерело даних, використане для цього запиту. Можливі значення: `LIVE_HLR` (запит HLR у реальному часі) або `MNP_DB` (статична база даних переносимості мобільних номерів). Див. опції маршрутизації для деталей.	false
`routing_instruction`	string	Рядок, розділений двокрапками, що описує інструкцію маршрутизації, використану в запиті. Перший компонент - `STATIC`, коли ви вказали маршрут, або `AUTO` для автоматичної маршрутизації; другий компонент - ідентифікатор маршруту, а для запитів з автоматичною маршрутизацією третій компонент показує джерело, на основі якого прийнято рішення про маршрутизацію (тобто `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`).	false

Статус	Опис
CONNECTED	Номер дійсний, і цільовий пристрій наразі підключений до мобільної мережі. Дзвінки, SMS та інші послуги мають успішно досягти одержувача.
ABSENT	Номер дійсний, але цільовий пристрій або вимкнений, або тимчасово поза зоною покриття мережі. Повідомлення або дзвінки можуть не бути доставлені до моменту повторного підключення пристрою до мережі.
INVALID_MSISDN	Номер недійсний або наразі не призначений жодному абоненту в мобільній мережі. Дзвінки та повідомлення на цей номер не будуть доставлені.
UNDETERMINED	Не вдалося визначити статус підключення номера. Це може бути спричинено недійсним номером, помилкою SS7 або відсутністю зв'язку з цільовим оператором мережі. Перевірте код помилки та його опис для додаткової діагностики.

Прокрутити вгору

POST/mnp-lookupзахищено

Виконує синхронну перевірку MNP та надає інформацію про переносимість мобільних номерів і мережу. Цей ендпоінт підходить, якщо ваша основна мета - отримати поточний MCCMNC заданого номера мобільного телефону та визначити оригінальну та поточну мережі в реальному часі.

Для масової обробки великих обсягів даних, які не потребують миттєвих результатів, розгляньте використання асинхронного POST /mnp-lookups, який оптимізовано для високошвидкісної пакетної обробки.

MNP-запити надійно визначають переносимість та інформацію про мережу, але не вказують, чи підключений цільовий мобільний телефон до мережі в даний момент і чи доступний він. Щоб отримати інформацію про підключення в реальному часі, будь ласка, використовуйте ендпоінт POST /hlr-lookup.

Запит Успішна відповідь Відповідь з помилкою

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookup' \
          -d "@payload.json"

Дані запиту

{
   "msisdn":"+14156226819",
   "route":null,
   "storage":null
}

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`msisdn`	string	Номер мобільного телефону (MSISDN) для запиту, наданий у міжнародному форматі (наприклад, +14156226819 або 0014156226819). Коди країн обов'язкові.	null	обов'язковий
`route`	string(3)	Необов'язковий тризначний ідентифікатор, що вказує маршрут для цього запиту. Встановіть значення `null` або пропустіть цей параметр, щоб застосувати ваше налаштування маршрутизації або дозволити системі автоматично визначити найкращий маршрут для цього запиту.	null	необов'язково
`storage`	string	Необов'язковий ідентифікатор сховища, що вказує звіт, де зберігатимуться результати для ручного перегляду, аналітики та звітності. Система автоматично додає позначку часу з поточним місяцем. Якщо пропущено або встановлено `null`, система автоматично групуватиме результати за місяцями для цілей звітності.	null	необов'язково

{
   "id":"e428acb1c0ae",
   "msisdn":"+14156226819",
   "query_status":"OK",
   "mccmnc":"310260",
   "mcc":"310",
   "mnc":"260",
   "is_ported":true,
   "original_network_name":"Verizon Wireless:6006 - SVR/2",
   "original_country_name":"United States",
   "original_country_code":"US",
   "original_country_prefix":"+1415",
   "ported_network_name":"T-Mobile US:6529 - SVR/2",
   "ported_country_name":"United States",
   "ported_country_code":"US",
   "ported_country_prefix":"+1",
   "extra":"LRN:4154250000",
   "cost":"0.0050",
   "timestamp":"2020-08-05 21:21:33.490+0300",
   "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
   "route":"PTX",
   "error_code":null
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`id`	string(12)	Унікальний 12-символьний ідентифікатор для цього запиту.	false
`msisdn`	string	Номер мобільного телефону, перевірений у цьому запиті.	false
`query_status`	string	Вказує, чи було успішно отримано інформацію про портування та мережу. Можливі значення: `OK` або `FAILED`.	false
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний MCCMNC (комбінація коду країни мобільного зв'язку та коду мобільної мережі), який ідентифікує мережу, до якої наразі належить номер мобільного телефону.	true
`mcc`	string(3)	Трисимвольний MCC (код країни мобільного зв'язку), що представляє країну, пов'язану з поточною мережею номера мобільного телефону.	true
`mnc`	string(2\|3)	Дво- або трисимвольний MNC (код мобільної мережі), який ідентифікує поточного оператора мережі для номера мобільного телефону.	true
`is_ported`	boolean	Вказує, чи було номер телефону перенесено з початкової мережі до нового оператора.	true
`original_network_name`	string	Довільний рядок (англійською мовою), що вказує назву початкового оператора мережі перевіреного номера мобільного телефону.	true
`original_country_name`	string	Довільний рядок (англійською мовою), що вказує початкову країну перевіреного номера мобільного телефону.	true
`original_country_code`	string(2)	Двосимвольний код країни за ISO, що представляє початкову країну перевіреного номера мобільного телефону.	true
`original_country_prefix`	string	Телефонний код початкової країни, пов'язаної з перевіреним номером мобільного телефону.	true
`ported_network_name`	string	Вказує оператора мережі, до якого було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`ported_country_name`	string	Вказує країну, до якої було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`ported_country_code`	string(2)	Двосимвольний код країни за ISO, що представляє країну, до якої було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`ported_country_prefix`	string	Телефонний код країни, до якої було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`extra`	string	Довільний рядок, що містить додаткову інформацію про номер телефону (за наявності).	true
`cost`	string	Десяткове значення, представлене як рядок, що вказує вартість цього запиту в EUR.	true
`timestamp`	string	Позначка часу у форматі W3C з інформацією про часовий пояс, що вказує, коли було завершено запит.	true
`storage`	string	Назва сховища (або назва звіту), до якого було додано результати запиту. Використовується для завантаження CSV та звітності через веб-інтерфейс.	true
`route`	string(3)	Трисимвольний ідентифікатор, що вказує маршрут, використаний для цього запиту.	true
`error_code`	integer	Додатковий внутрішній код помилки, що надає додатковий контекст для діагностики службою підтримки клієнтів.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

POST/mnp-lookupsзахищено

Ініціює пакетну асинхронну перевірку MNP (переносимість мобільних номерів), отримуючи поточний MCCMNC та визначаючи оригінальну та поточну мережі в режимі реального часу. Результати надсилаються через вебхуки на ваш сервер. Цей метод оптимізовано для обробки великих обсягів номерів, які не потребують миттєвої відповіді, наприклад для очищення та перевірки баз даних. Для додатків реального часу, таких як маршрутизація дзвінків або доставка SMS, розгляньте використання ендпоінту POST /mnp-lookup.

MNP-запити надійно визначають переносимість та інформацію про мережу, але не вказують, чи підключений цільовий мобільний телефон до мережі в даний момент і чи доступний він. Щоб отримати інформацію про підключення в реальному часі, будь ласка, використовуйте ендпоінт POST /hlr-lookups.

Перед використанням цього ендпоінту переконайтеся, що налаштовано URL вебхука для асинхронного отримання результатів запитів. Ви можете налаштувати це у ваших налаштуваннях API.

Запит Успішна відповідь Відповідь з помилкою Вебхуки

curl -X POST 'https://www.hlr-lookups.com/api/v2/mnp-lookups' \
          -d "@payload.json"

Дані запиту

{
   "msisdns":["+14156226819","+491788735000","+905536939460"],
   "route":null,
   "storage":null
}

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`msisdns`	array	Масив номерів мобільних телефонів (MSISDN) у міжнародному форматі (наприклад, +14156226819 або 0014156226819). Ви можете включити до 1000 номерів на запит.	null	обов'язковий
`route`	string(3)	Необов'язковий тризначний ідентифікатор, що визначає маршрут для цієї перевірки. Встановіть значення `null` або пропустіть цей параметр, щоб застосувати вашу користувацьку карту маршрутизації або дозволити нашій системі автоматично визначити найкращі маршрути для цього запиту.	null	необов'язково
`storage`	string	Необов'язковий ідентифікатор сховища, що вказує звіт, де зберігатимуться результати для ручного перегляду, аналітики та звітності. Система автоматично додає позначку часу з поточним місяцем. Якщо пропущено або встановлено `null`, система автоматично групуватиме результати за місяцями для цілей звітності.	null	необов'язково

{
   "accepted":[
      {
         "id":"0424928f332e",
         "msisdn":"+491788735000"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "msisdn":"+31"
      }
   ],
   "rejected_count":1,
   "total_count":2,
   "cost":"0.01",
   "storage":"ASYNC-API-2020-08",
   "route":"IP1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`accepted`	array	Список об'єктів, що містять унікальні ідентифікатори та MSISDN, які прийняті до обробки.	false
`accepted_count`	integer	Загальна кількість MSISDN, успішно прийнятих до обробки.	false
`rejected`	array	Список об'єктів, що містять унікальні ідентифікатори та MSISDN, які відхилені від обробки, зазвичай через недійсні номери. Відхилені записи не тарифікуються.	false
`rejected_count`	integer	Загальна кількість MSISDN, відхилених через помилки валідації.	false
`total_count`	integer	Загальна кількість прийнятих та відхилених MSISDN, які були подані на обробку.	false
`cost`	string	Десяткове значення, представлене як рядок, що вказує загальну вартість у євро для прийнятих запитів.	false
`storage`	string	Назва сховища, куди додаються результати запитів, використовується для звітності та завантаження CSV через веб-інтерфейс.	false
`route`	string(3)	Трисимвольний ідентифікатор, що вказує маршрут, використаний для цього запиту.	false
`webhook_urls`	array	URL-адреси вебхуків, налаштовані у ваших налаштуваннях API. Результати надсилаються сюди.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Обробка вебхуків

Після надсилання наша платформа починає обробку наданих номерів телефонів і надсилає результати на попередньо вказану URL-адресу вебхука на вашому сервері. Результати передаються як HTTP POST запит з JSON-об'єктом у тілі запиту.

Автентифікація

Автентифікуйте вебхук, перевіривши HTTP-заголовок X-Signatures.

Заголовок X-Signatures містить список підписів, розділених крапкою з комою. Кожен підпис у списку генерується за допомогою одного з API-секретів, налаштованих у вашому обліковому записі. Щоб перевірити вебхук, згенеруйте SHA-256 хеш, використовуючи ваш API-ключ, секрет і необроблене тіло HTTP - потім порівняйте його з підписами у списку.

Збіг підтверджує, що запит автентичний і підписаний секретом, яким ви керуєте.

Приклад коду

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

Запит є дійсним, якщо будь-який із підписів, наданих у заголовку, дорівнює SHA256 хешу, обчисленому для об'єднаного рядка вашого API-ключа, секрету та тіла HTTP.

Підтвердження отримання

Очікується, що ваш сервер відповість HTTP-кодом статусу 200 OK для підтвердження успішного отримання. Якщо повертається будь-який інший код відповіді, виникає тайм-аут (10 секунд) або виникає будь-яка інша проблема з доставкою, система автоматично повторить спробу надсилання вебхука через одну хвилину. Якщо запит продовжує завершуватися невдачею, повторні спроби виконуватимуться за стратегією експоненційної затримки з наступними спробами через 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 хвилин.

Цей механізм повторних спроб забезпечує максимальну надійність доставки результатів перевірок до вашої інфраструктури. Це мінімізує ризик втрати даних через тимчасові проблеми з мережею або недоступність сервера.

Дані вебхука

{
    "type":"MNP",
    "results":[
        {
           "id":"e428acb1c0ae",
           "msisdn":"+14156226819",
           "query_status":"OK",
           "mccmnc":"310260",
           "mcc":"310",
           "mnc":"260",
           "is_ported":true,
           "original_network_name":"Verizon Wireless:6006 - SVR/2",
           "original_country_name":"United States",
           "original_country_code":"US",
           "original_country_prefix":"+1415",
           "ported_network_name":"T-Mobile US:6529 - SVR/2",
           "ported_country_name":"United States",
           "ported_country_code":"US",
           "ported_country_prefix":"+1",
           "extra":"LRN:4154250000",
           "cost":"0.0050",
           "timestamp":"2020-08-05 21:21:33.490+0300",
           "storage":"WEB-CLIENT-SOLO-MNP-2020-08",
           "route":"PTX",
           "error_code":null
        }
    ]
}

Атрибути payload вебхука

Об'єкт JSON містить атрибут type => MNP разом з атрибутом results, який включає список об'єктів запитів, як задокументовано нижче.

Ім'я	Тип	Опис	Необов'язковий
`id`	string(12)	Унікальний 12-символьний ідентифікатор для цього запиту.	false
`msisdn`	string	Номер мобільного телефону, перевірений у цьому запиті.	false
`query_status`	string	Вказує, чи було успішно отримано інформацію про портування та мережу. Можливі значення: `OK` або `FAILED`.	false
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний MCCMNC (комбінація коду країни мобільного зв'язку та коду мобільної мережі), який ідентифікує мережу, до якої наразі належить номер мобільного телефону.	true
`mcc`	string(3)	Трисимвольний MCC (код країни мобільного зв'язку), що представляє країну, пов'язану з поточною мережею номера мобільного телефону.	true
`mnc`	string(2\|3)	Дво- або трисимвольний MNC (код мобільної мережі), який ідентифікує поточного оператора мережі для номера мобільного телефону.	true
`is_ported`	boolean	Вказує, чи було номер телефону перенесено з початкової мережі до нового оператора.	true
`original_network_name`	string	Довільний рядок (англійською мовою), що вказує назву початкового оператора мережі перевіреного номера мобільного телефону.	true
`original_country_name`	string	Довільний рядок (англійською мовою), що вказує початкову країну перевіреного номера мобільного телефону.	true
`original_country_code`	string(2)	Двосимвольний код країни за ISO, що представляє початкову країну перевіреного номера мобільного телефону.	true
`original_country_prefix`	string	Телефонний код початкової країни, пов'язаної з перевіреним номером мобільного телефону.	true
`ported_network_name`	string	Вказує оператора мережі, до якого було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`ported_country_name`	string	Вказує країну, до якої було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`ported_country_code`	string(2)	Двосимвольний код країни за ISO, що представляє країну, до якої було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`ported_country_prefix`	string	Телефонний код країни, до якої було перенесено перевірений номер мобільного телефону, якщо застосовно.	true
`extra`	string	Довільний рядок, що містить додаткову інформацію про номер телефону (за наявності).	true
`cost`	string	Десяткове значення, представлене як рядок, що вказує вартість цього запиту в EUR.	true
`timestamp`	string	Позначка часу у форматі W3C з інформацією про часовий пояс, що вказує, коли було завершено запит.	true
`storage`	string	Назва сховища (або назва звіту), до якого було додано результати запиту. Використовується для завантаження CSV та звітності через веб-інтерфейс.	true
`route`	string(3)	Трисимвольний ідентифікатор, що вказує маршрут, використаний для цього запиту.	true
`error_code`	integer	Додатковий внутрішній код помилки, що надає додатковий контекст для діагностики службою підтримки клієнтів.	true

Прокрутити вгору

POST/nt-lookupзахищено

Виконує синхронний запит визначення типу номера (NT). Цей ендпоінт ідеально підходить, якщо ваша основна мета - визначити в реальному часі, чи належать надані телефонні номери до стаціонарних, мобільних, преміум-тарифів, VoIP, пейджерів або інших діапазонів нумерації.

NT-запити надійно визначають тип телефонного номера, однак вони не вказують, чи цільовий номер наразі підключений до мережі та доступний. Щоб отримати інформацію про актуальну підключеність, будь ласка, використовуйте ендпоінт POST /hlr-lookup.

Якщо ваш сценарій використання вимагає точної інформації про мережу та переносимість (MCCMNC), але не вимагає статусу підключеності в реальному часі, будь ласка, використовуйте ендпоінт POST /mnp-lookup для запитів про переносимість мобільних номерів.

Запит Успішна відповідь Відповідь з помилкою Довідник типів

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookup' \
          -d "@payload.json"

Дані запиту

{
   "number":"+14156226819",
   "route":null,
   "storage":null
}

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`number`	string	Телефонний номер у міжнародному форматі (наприклад, +4989702626 або 004989702626).	null	mandatory
`route`	string(3)	Необов'язковий трисимвольний ідентифікатор, що визначає маршрут для цього запиту. Встановіть значення `null` або пропустіть цей параметр, щоб застосувати вашу власну карту маршрутизації або дозволити нашій системі автоматично визначити найкращі маршрути для цього запиту.	null	необов'язково
`storage`	string	Необов'язковий ідентифікатор сховища, що вказує звіт, де зберігатимуться результати для ручного перегляду, аналітики та звітності. Система автоматично додає позначку часу з поточним місяцем. Якщо пропущено або встановлено `null`, система автоматично групуватиме результати за місяцями для цілей звітності.	null	необов'язково

{
     "id":"2ed0788379c6",
     "number":"+4989702626",
     "number_type":"LANDLINE",
     "query_status":"OK",
     "is_valid":true,
     "invalid_reason":null,
     "is_possibly_ported":false,
     "is_vanity_number":false,
     "qualifies_for_hlr_lookup":false,
     "mccmnc":null,
     "mcc":null,
     "mnc":null,
     "original_network_name":null,
     "original_country_name":"Germany",
     "original_country_code":"DE",
     "regions":[
        "Munich"
     ],
     "timezones":[
        "Europe/Berlin"
     ],
     "info_text":"This is a landline number.",
     "cost":"0.0050",
     "timestamp":"2015-12-04 10:36:41.866283+00",
     "storage":"SYNC-API-NT-2015-12",
     "route":"LC1"
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`id`	string(12)	Унікальний ідентифікатор, присвоєний цьому запиту на перевірку.	false
`number`	string	Номер телефону, який було перевірено під час цього запиту.	false
`number_type`	string	Виявлений тип номера. Можливі значення: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Вказує, чи було успішно отримано інформацію про тип номера. Повертає `OK` у разі успіху або `FAILED` у разі невдачі запиту.	false
`is_valid`	boolean	Вказує, чи є номер телефону синтаксично коректним.	true
`invalid_reason`	string	Текстове повідомлення англійською мовою, що пояснює, чому номер телефону вважається некоректним (наприклад, "too short" або "invalid prefix"), або `null`, якщо номер коректний.	true
`is_possibly_ported`	boolean	Вказує, чи міг номер телефону бути перенесений від первинного оператора до іншого. Для точної інформації про переносимість використовуйте MNP-запити.	true
`is_vanity_number`	boolean	Вказує, чи є номер телефону іменним номером, тобто містить буквені символи.	true
`qualifies_for_hlr_lookup`	boolean	Вказує, чи підходить номер телефону для додаткових запитів через HLR-перевірки.	true
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний рядок, що представляє кортеж MCCMNC (код мобільної країни та код мобільної мережі), який ідентифікує первинну мережу мобільного номера телефону.	true
`mcc`	string(3)	Трисимвольний рядок, що представляє MCC (код мобільної країни), який ідентифікує країну, пов'язану з первинною мобільною мережею номера телефону.	true
`mnc`	string(2\|3)	Дво- або трисимвольний рядок, що представляє MNC (код мобільної мережі), який ідентифікує первинного оператора мобільного зв'язку номера телефону.	true
`original_network_name`	string	Довільний текстовий рядок англійською мовою, що вказує назву первинного оператора мережі перевіреного мобільного номера телефону.	true
`original_country_name`	string	Довільний текстовий рядок англійською мовою, що вказує первинну країну, пов'язану з перевіреним мобільним номером телефону.	true
`original_country_code`	string(2)	Двосимвольний код країни ISO, що вказує первинну країну перевіреного мобільного номера телефону.	true
`regions`	array	Список зрозумілих текстових рядків англійською мовою, що вказують географічний регіон (регіони), пов'язані з цим номером телефону.	true
`timezones`	array	Список часових поясів (у форматі Olson), пов'язаних з цим номером телефону.	true
`info_text`	string	Довільний рядок, який може містити додаткову інформацію про номер телефону.	true
`cost`	string	Десяткове значення, представлене як рядок, що вказує вартість (у EUR) цієї перевірки.	true
`timestamp`	string	Мітка часу у форматі W3C (включаючи часовий пояс), що вказує, коли перевірку було завершено.	true
`storage`	string	Вказує назву сховища, куди було додано результати перевірки. Це відповідає назві звіту, що використовується для завантаження CSV та аналітики через веб-інтерфейс.	true
`route`	string(3)	Трисимвольний ідентифікатор, що вказує маршрут, використаний для цього запиту.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Тип	Опис
LANDLINE	Стаціонарний телефонний номер.
MOBILE	Мобільний телефонний номер. Підходить для HLR-запитів для отримання додаткової інформації про статус підключення, мережу, переносимість та роумінг.
MOBILE_OR_LANDLINE	Стаціонарний або мобільний телефонний номер. Може підходити для HLR-запиту.
TOLL_FREE	Безкоштовний телефонний номер.
PREMIUM_RATE	Телефонний номер з преміум-тарифікацією та додатковими платежами.
SHARED_COST	Телефонний номер зі спільною оплатою. Зазвичай дешевший, ніж номери з преміум-тарифікацією.
VOIP	Телефонний номер Voice over IP. Включає номери TSoIP (телефонний сервіс через IP).
PAGER	Номер пейджера. Зазвичай без голосового функціоналу.
UAN	Універсальний номер доступу (корпоративний номер). Може бути перенаправлений до конкретних офісів, але дозволяє використовувати один номер для всієї компанії.
VOICEMAIL	Номер голосової пошти.
UNKNOWN	Не вдалося визначити тип номера.

Прокрутити вгору

POST/nt-lookups захищено

Цей ендпоінт ініціює серію асинхронних перевірок типу номера з поверненням результатів на ваш сервер через webhook. Підходить, якщо ваша основна мета - визначити, чи належать вказані телефонні номери до стаціонарних, мобільних, преміум-тарифів, VoIP, пейджерів або інших діапазонів нумерації. Оптимізовано для швидкої обробки великих обсягів номерів, цей ендпоінт ідеально підходить для масових операцій (наприклад, очищення бази даних). Для реального трафіку та критичних за часом випадків використовуйте натомість ендпоінт POST /nt-lookup.

Для виклику цього ендпоінта необхідно вказати URL webhook у ваших налаштуваннях API.

Запит Успішна відповідь Відповідь з помилкою Вебхуки Довідник типів

curl -X POST 'https://www.hlr-lookups.com/api/v2/nt-lookups' \
          -d "@payload.json"

Дані запиту

{
   "numbers":["+14156226819","+4989702626"],
   "route":null,
   "storage":null
}

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`numbers`	array	Масив телефонних номерів у міжнародному форматі (наприклад, +14156226819 або 004989702626). Максимум 1000 номерів можна включити в один запит.	null	обов'язковий
`route`	string(3)	Необов'язковий триcимвольний ідентифікатор, що вказує маршрут для цієї перевірки. Встановіть значення `null` або пропустіть цей параметр, щоб застосувати вашу користувацьку карту маршрутизації або дозволити нашій системі автоматично визначити найкращий маршрут для цього запиту.	null	необов'язково
`storage`	string	Необов'язковий ідентифікатор сховища, що вказує звіт, де зберігатимуться результати для ручного перегляду, аналітики та звітності. Система автоматично додає позначку часу з поточним місяцем. Якщо пропущено або встановлено `null`, система автоматично групуватиме результати за місяцями для цілей звітності.	null	необов'язково

{
   "accepted":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460"
      }
   ],
   "accepted_count":1,
   "rejected":[
      {
         "id":null,
         "number":"+31"
      }
   ],
   "rejected_count":2,
   "total_count":3,
   "cost":0.005,
   "storage":"ASYNC-API-NT-2020-08",
   "route":"LC1",
   "webhook_urls":[
      "https://your-server.com/endpoint"
   ]
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`accepted`	array	Масив об'єктів, кожен з яких містить унікальний ідентифікатор і телефонний номер, прийнятий для обробки.	false
`accepted_count`	integer	Загальна кількість телефонних номерів, прийнятих для обробки.	false
`rejected`	array	Масив об'єктів, кожен з яких містить унікальний ідентифікатор і телефонний номер, відхилений для обробки. Зазвичай ці номери є недійсними, і плата не стягується.	false
`rejected_count`	integer	Загальна кількість телефонних номерів, відхилених для обробки.	false
`total_count`	integer	Загальна кількість прийнятих і відхилених телефонних номерів, поданих для обробки.	false
`cost`	string	Рядок, що представляє десяткове значення, яке вказує вартість у євро для цих перевірок.	false
`storage`	string	Назва сховища (звіту), до якого додано результати перевірки. Ця назва використовується для завантаження CSV і аналітики через веб-інтерфейс.	false
`route`	string(3)	Трисимвольний ідентифікатор, що вказує маршрут, використаний для цього запиту перевірки.	false
`webhook_urls`	array	URL-адреси вебхуків, налаштовані у ваших налаштуваннях API. Результати надсилаються сюди.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Обробка вебхуків

Після надсилання наша платформа починає обробку наданих номерів телефонів і надсилає результати на попередньо вказану URL-адресу вебхука на вашому сервері. Результати передаються як HTTP POST запит з JSON-об'єктом у тілі запиту.

Автентифікація

Автентифікуйте вебхук, перевіривши HTTP-заголовок X-Signatures.

Заголовок X-Signatures містить список підписів, розділених крапкою з комою. Кожен підпис у списку генерується за допомогою одного з API-секретів, налаштованих у вашому обліковому записі. Щоб перевірити вебхук, згенеруйте SHA-256 хеш, використовуючи ваш API-ключ, секрет і необроблене тіло HTTP - потім порівняйте його з підписами у списку.

Збіг підтверджує, що запит автентичний і підписаний секретом, яким ви керуєте.

Приклад коду

$signaturesHeader = (getallheaders() ?? [])['X-Signatures'] ?? ''; // list of signatures
$key = getenv('AUTH_KEY'); // Your API Key
$secret = getenv('AUTH_SECRET'); // Your API Secret
$payload = file_get_contents('php://input'); // The HTTP body of the incoming POST request

// Generate the expected signature
$expectedSignature = hash('sha256', $key . $secret . $payload);

// Split the header into individual signatures
$providedSignatures = explode(';', $signaturesHeader);

// Check if any signature matches
$valid = false;
foreach ($providedSignatures as $sig) {
    if (hash_equals($expectedSignature, $sig)) {
        $valid = true;
        break;
    }
}

Запит є дійсним, якщо будь-який із підписів, наданих у заголовку, дорівнює SHA256 хешу, обчисленому для об'єднаного рядка вашого API-ключа, секрету та тіла HTTP.

Підтвердження отримання

Очікується, що ваш сервер відповість HTTP-кодом статусу 200 OK для підтвердження успішного отримання. Якщо повертається будь-який інший код відповіді, виникає тайм-аут (10 секунд) або виникає будь-яка інша проблема з доставкою, система автоматично повторить спробу надсилання вебхука через одну хвилину. Якщо запит продовжує завершуватися невдачею, повторні спроби виконуватимуться за стратегією експоненційної затримки з наступними спробами через 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 хвилин.

Цей механізм повторних спроб забезпечує максимальну надійність доставки результатів перевірок до вашої інфраструктури. Це мінімізує ризик втрати даних через тимчасові проблеми з мережею або недоступність сервера.

Дані вебхука

{
   "type":"NT",
   "results":[
      {
         "id":"9f8a52cfa7d2",
         "number":"+905536939460",
         "numbertype":"MOBILE",
         "state":"COMPLETED",
         "isvalid":"Yes",
         "invalidreason":null,
         "ispossiblyported":"Yes",
         "isvanitynumber":"No",
         "qualifiesforhlrlookup":"Yes",
         "originalcarrier":"Turk Telekom (AVEA)",
         "mccmnc":"28603",
         "mcc":"286",
         "mnc":"03",
         "countrycode":"TR",
         "regions":[
            "Turkey"
         ],
         "timezones":[
            "Europe\/Istanbul"
         ],
         "infotext":"This number qualifies for HLR lookups. Determine if this subscriber number is connected, absent or invalid by running an HLR lookup. This is a mobile number and might be in roaming state. Run an HLR lookup to obtain roaming information (if available). This number is possibly ported and the carrier information might be inaccurate. To obtain portability information run an HLR lookup.",
         "usercharge":"0.0050",
         "inserttime":"2020-08-13 01:57:15.897+0300",
         "storage":"ASYNC-API-NT-2020-08",
         "route":"LC1",
         "interface":"Async API"
      }
   ]
}

Атрибути payload вебхука

Об'єкт JSON містить атрибут type => NT разом з атрибутом results, який включає список об'єктів запитів, як задокументовано нижче.

Ім'я	Тип	Опис	Необов'язковий
`id`	string(12)	Унікальний ідентифікатор, присвоєний цьому запиту на перевірку.	false
`number`	string	Номер телефону, який було перевірено під час цього запиту.	false
`number_type`	string	Виявлений тип номера. Можливі значення: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Вказує, чи було успішно отримано інформацію про тип номера. Повертає `OK` у разі успіху або `FAILED` у разі невдачі запиту.	false
`is_valid`	boolean	Вказує, чи є номер телефону синтаксично коректним.	true
`invalid_reason`	string	Текстове повідомлення англійською мовою, що пояснює, чому номер телефону вважається некоректним (наприклад, "too short" або "invalid prefix"), або `null`, якщо номер коректний.	true
`is_possibly_ported`	boolean	Вказує, чи міг номер телефону бути перенесений від первинного оператора до іншого. Для точної інформації про переносимість використовуйте MNP-запити.	true
`is_vanity_number`	boolean	Вказує, чи є номер телефону іменним номером, тобто містить буквені символи.	true
`qualifies_for_hlr_lookup`	boolean	Вказує, чи підходить номер телефону для додаткових запитів через HLR-перевірки.	true
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний рядок, що представляє кортеж MCCMNC (код мобільної країни та код мобільної мережі), який ідентифікує первинну мережу мобільного номера телефону.	true
`mcc`	string(3)	Трисимвольний рядок, що представляє MCC (код мобільної країни), який ідентифікує країну, пов'язану з первинною мобільною мережею номера телефону.	true
`mnc`	string(2\|3)	Дво- або трисимвольний рядок, що представляє MNC (код мобільної мережі), який ідентифікує первинного оператора мобільного зв'язку номера телефону.	true
`original_network_name`	string	Довільний текстовий рядок англійською мовою, що вказує назву первинного оператора мережі перевіреного мобільного номера телефону.	true
`original_country_name`	string	Довільний текстовий рядок англійською мовою, що вказує первинну країну, пов'язану з перевіреним мобільним номером телефону.	true
`original_country_code`	string(2)	Двосимвольний код країни ISO, що вказує первинну країну перевіреного мобільного номера телефону.	true
`regions`	array	Список зрозумілих текстових рядків англійською мовою, що вказують географічний регіон (регіони), пов'язані з цим номером телефону.	true
`timezones`	array	Список часових поясів (у форматі Olson), пов'язаних з цим номером телефону.	true
`info_text`	string	Довільний рядок, який може містити додаткову інформацію про номер телефону.	true
`cost`	string	Десяткове значення, представлене як рядок, що вказує вартість (у EUR) цієї перевірки.	true
`timestamp`	string	Мітка часу у форматі W3C (включаючи часовий пояс), що вказує, коли перевірку було завершено.	true
`storage`	string	Вказує назву сховища, куди було додано результати перевірки. Це відповідає назві звіту, що використовується для завантаження CSV та аналітики через веб-інтерфейс.	true
`route`	string(3)	Трисимвольний ідентифікатор, що вказує маршрут, використаний для цього запиту.	true

Тип	Опис
LANDLINE	Стаціонарний телефонний номер.
MOBILE	Мобільний телефонний номер. Підходить для HLR-запитів для отримання додаткової інформації про статус підключення, мережу, переносимість та роумінг.
MOBILE_OR_LANDLINE	Стаціонарний або мобільний телефонний номер. Може підходити для HLR-запиту.
TOLL_FREE	Безкоштовний телефонний номер.
PREMIUM_RATE	Телефонний номер з преміум-тарифікацією та додатковими платежами.
SHARED_COST	Телефонний номер зі спільною оплатою. Зазвичай дешевший, ніж номери з преміум-тарифікацією.
VOIP	Телефонний номер Voice over IP. Включає номери TSoIP (телефонний сервіс через IP).
PAGER	Номер пейджера. Зазвичай без голосового функціоналу.
UAN	Універсальний номер доступу (корпоративний номер). Може бути перенаправлений до конкретних офісів, але дозволяє використовувати один номер для всієї компанії.
VOICEMAIL	Номер голосової пошти.
UNKNOWN	Не вдалося визначити тип номера.

Прокрутити вгору

GET/routeзахищено

Отримує маршрут, який буде автоматично обрано при виконанні HLR-запиту без вказівки параметра route.

Автоматичний вибір маршруту базується на карті маршрутизації, яку можна отримати через ендпоінт GET /hlr-coverage, що в основному формується на основі GET /routing-map. Ви можете налаштувати свою карту маршрутизації та визначити власні правила в налаштуваннях облікового запису.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/route?msisdn=+491788735000'

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`msisdn`	string	MSISDN, для якого потрібно отримати автоматично обрану інформацію про маршрутизацію.	null	обов'язковий

{
   "route":"V11",
   "confidence_level":"HIGH",
   "mccmnc":"26203",
   "origin":"SCORE"
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`route`	string	Рекомендований маршрут.	false
`confidence_level`	string	Рівень впевненості, з яким було вибрано цей маршрут, тобто `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	MCCMNC на основі плану нумерації для цього номера.	false
`origin`	string	Джерело, на основі якого прийнято рішення про маршрутизацію, тобто `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/routesзахищено

Цей ендпоінт повертає список доступних маршрутів HLR, MNP та NT. Кожен маршрут разом з його функціями та обмеженнями пояснюється на сторінці деталі маршрутизації.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/routes'

{
   "routes":{
      "HLR":[
         "V11",
         "E10",
         "MS9",
         "DV8",
         "SV3",
         "IP1"
      ],
      "MNP":[
         "PTX",
         "IP4"
      ],
      "NT":[
         "LC1"
      ]
   }
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`routes`	object	Об'єкт з маршрутами, згрупованими за типом маршруту.	false
`HLR\|MNP\|NT`	string[]	Містить список ідентифікаторів маршрутів.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/routing-mapзахищено

Отримує конфігурацію автоматичної маршрутизації, яка наразі застосовується до HLR-запитів для вашого облікового запису. Ця конфігурація за замовчуванням використовується щоразу, коли ви надсилаєте HLR-запити без вказівки параметра route. Ви можете налаштувати карту маршрутизації та створити власні правила в налаштуваннях облікового запису.

Ієрархія конфігурації каскадується від правил на рівні країни до правил на рівні MCCMNC, і нарешті до зіставлень окремих префіксів телефонних номерів. На практиці це означає, що зіставлення окремих префіксів телефонних номерів мають пріоритет над конфліктуючими призначеннями MCCMNC, які, у свою чергу, перевизначають правила на рівні країни. Зверніть увагу, що резервний MNP перевизначає будь-які конфліктуючі користувацькі правила, поки він увімкнений.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/routing-map'

{
   "routing":{
      "map":{
         "defaultRoute":"V11",
         "mnpFallback":true,
         "mccmncs":[
            {
               "mccmnc":20201,
               "countrycode":"GR",
               "route":"E10",
               "mno":"Cosmote",
               "confidence":"HIGH",
               "origin":"SCORE"
            }
         ],
         "prefixes":[
            {
               "countrycode":"DE",
               "cns":"+4917821",
               "route":"DV8",
               "mccmnc":"26203",
               "mno":"O2"
            }
         ],
         "countries":[
            {
               "countrycode":"US",
               "route":"DV8"
            }
         ]
      }
   }
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`default_route`	string	Маршрут за замовчуванням, який використовується, коли неможливо визначити бажаний варіант маршрутизації для MSISDN і не застосовуються користувацькі правила маршрутизації.	false
`mnp_fallback`	boolean	Вказує, чи увімкнено резервний MNP. Коли увімкнено і HLR-запити не підтримуються мережею (статус підключення недоступний), система виконає MNP-запит натомість.	false
`mccmncs`	array	Зіставлення кодів MCCMNC з їх автоматично вибраними маршрутами. Під час виконання HLR-запиту для номера в певному MCCMNC використовується відповідний маршрут.	false
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний MCCMNC (комбінація коду мобільної країни та коду мобільної мережі), що ідентифікує оператора мобільного зв'язку.	false
`countrycode`	string(2)	Двосимвольний код країни ISO, що ідентифікує країну мережі.	false
`route`	string(3)	Вибраний маршрут для мережі.	false
`mno`	string	Споживчий бренд, під яким працює ця мережа.	false
`confidence`	string	Рівень впевненості, з яким було зроблено вибір. Можливі значення: HIGH, NORMAL, LOW, MNP_REDIRECT. У випадку останнього, система перенаправляє трафік до цієї мережі на MNP, якщо така поведінка увімкнена у вашому обліковому записі. Інакше використовується маршрут за замовчуванням в обліковому записі.	false
`origin`	string	Джерело, на якому базується вибір. Можливі значення: `SCORE`, `CUSTOM_GLOBAL_COUNTRY`, `CUSTOM_GLOBAL_MCCMNC`, `CUSTOM_GLOBAL_PREFIX`, `CUSTOM_USER_COUNTRY`, `CUSTOM_USER_MCCMNC`, `CUSTOM_USER_PREFIX`, `MNP_FALLBACK`, `PLATFORM_DEFAULT`, `USER_DEFAULT`	false
`prefixes`	array	Список користувацьких правил маршрутизації на основі префіксів, налаштованих у вашому обліковому записі, якщо такі є.	false
`countrycode`	string(2)	Двосимвольний код країни ISO, що ідентифікує країну префікса.	false
`cns`	string	Префікс, до якого застосовується правило маршрутизації.	false
`route`	string(3)	Вибраний маршрут для префікса.	false
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний MCCMNC (комбінація коду мобільної країни та коду мобільної мережі), що ідентифікує оператора мобільного зв'язку.	true
`mno`	string	Споживчий бренд, під яким працює ця мережа.	true
`countries`	array	Список користувацьких правил на основі країн, налаштованих у вашому обліковому записі, якщо такі є.	false
`countrycode`	string(2)	Двосимвольний код країни ISO, що ідентифікує країну.	false
`route`	string(3)	Вибраний маршрут для країни.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/hlr-coverage захищено

Повертає аналітичні дані HLR-покриття для підтримки прийняття рішень на основі даних. Ця кінцева точка допомагає аналізувати параметри маршрутизації HLR у реальному часі через мобільні мережі, визначати найефективніші шляхи для ваших цільових регіонів та налаштовувати автоматичну маршрутизацію.

Рекомендовані маршрути з GET /route базуються на даних покриття, отриманих тут. Дані покриття також доступні на сторінці покриття мережі. Ви можете додатково налаштувати карту маршрутизації та визначити правила у налаштуваннях облікового запису.

Рекомендуємо ознайомитися з цим посібником для інтерпретації результатів.

Запит Успішна відповідь Відповідь з помилкою Довідник статусів

curl 'https://www.hlr-lookups.com/api/v2/hlr-coverage?countrycode=XX'

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`countrycode`	string(2)	Обов'язковий двосимвольний код країни ISO, який використовується для фільтрації результатів, повертаючи лише записи, пов'язані з вказаною країною.	null	обов'язковий
`sample_size`	string	Необов'язковий параметр, що визначає розмір вибірки. Можливі значення: `LARGE`, `MEDIUM`, `SMALL`. Більші вибірки охоплюють довший період часу, менші вибірки охоплюють найновіший період.	LARGE	необов'язково

{
   "name":"Germany",
   "countrycode":"DE",
   "prefix":"+49",
   "mccs":[
      "262"
   ],
   "carriers":[
      {
         "mno":"Telekom",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "routes":[
            {
               "route":"V11",
               "selected":true,
               "selection_confidence":"HIGH",
               "n":361579,
               "CONNECTED":275273,
               "CONNECTED_PCT":76.13,
               "ABSENT":21529,
               "ABSENT_PCT":5.95,
               "INVALID_MSISDN":62582,
               "INVALID_MSISDN_PCT":17.3,
               "UNDETERMINED":2195,
               "UNDETERMINED_PCT":0.6
            },
            {
               "route":"E10",
               "selected":false,
               "selection_confidence":null,
               "n":122600,
               "CONNECTED":13721,
               "CONNECTED_PCT":11.19,
               "ABSENT":133,
               "ABSENT_PCT":0.1,
               "INVALID_MSISDN":55,
               "INVALID_MSISDN_PCT":0.04,
               "UNDETERMINED":108691,
               "UNDETERMINED_PCT":88.65
            }
         ]
      }
   ]
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`name`	string	Назва вибраної країни англійською мовою у звичайному текстовому форматі.	false
`countrycode`	string(2)	Двосимвольний код країни ISO вибраної країни.	false
`prefix`	string	Міжнародний телефонний префікс вибраної країни.	false
`mccs`	string[]	Список MCC (мобільних кодів країни), пов'язаних з вибраною країною.	false
`carriers`	object[]	Список об'єктів операторів з метриками підключення для конкретних маршрутів.	false
`mno`	string	Назва оператора мобільного зв'язку англійською мовою у звичайному текстовому форматі.	false
`mccmnc`	string	MCCMNC оператора мобільного зв'язку.	false
`mcc`	string	MCC (мобільний код країни) оператора мобільного зв'язку.	false
`mnc`	string	MNC (мобільний код мережі) оператора мобільного зв'язку.	false
`routes`	object[]	Список результатів підключення для конкретних маршрутів.	false
`route`	string	Маршрут, до якого застосовується інформація про підключення.	false
`selected`	bool	Вказує, чи є це вибраним маршрутом для автоматичної маршрутизації.	false
`selection_confidence`	string	Рівень впевненості, з яким було вибрано цей маршрут, тобто `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Містить null, якщо це не вибраний маршрут.	true
`n`	int	Загальна кількість запитів у цій вибірці.	false
`CONNECTED`	int	Кількість HLR-запитів, які повернули статус CONNECTED.	false
`CONNECTED_PCT`	float	Відсоток HLR-запитів, які повернули статус CONNECTED.	false
`ABSENT`	int	Кількість HLR-запитів, які повернули статус ABSENT.	false
`ABSENT_PCT`	float	Відсоток HLR-запитів, які повернули статус ABSENT.	false
`INVALID_MSISDN`	int	Кількість HLR-запитів, які повернули статус INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Відсоток HLR-запитів, які повернули статус INVALID_MSISDN.	false
`UNDETERMINED`	int	Кількість HLR-запитів, які повернули статус UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Відсоток HLR-запитів, які повернули статус UNDETERMINED.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Статус	Опис
CONNECTED	Номер дійсний, і цільовий пристрій наразі підключений до мобільної мережі. Дзвінки, SMS та інші послуги мають успішно досягти одержувача.
ABSENT	Номер дійсний, але цільовий пристрій або вимкнений, або тимчасово поза зоною покриття мережі. Повідомлення або дзвінки можуть не бути доставлені до моменту повторного підключення пристрою до мережі.
INVALID_MSISDN	Номер недійсний або наразі не призначений жодному абоненту в мобільній мережі. Дзвінки та повідомлення на цей номер не будуть доставлені.
UNDETERMINED	Не вдалося визначити статус підключення номера. Це може бути спричинено недійсним номером, помилкою SS7 або відсутністю зв'язку з цільовим оператором мережі. Перевірте код помилки та його опис для додаткової діагностики.

Прокрутити вгору

GET/mnp-coverageзахищено

Цей ендпоінт повертає список операторів мобільного зв'язку разом з їхніми відповідними ідентифікаторами MCCMNC, які наразі підтримуються для перевірок переносу мобільних номерів.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/mnp-coverage?countrycode=XX'

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`countrycode`	string(2)	Необов'язковий двобуквений код країни ISO, який використовується для фільтрації результатів MCCMNC, повертаючи лише дані, що стосуються вказаної країни.	null	необов'язково

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`items[]`	array	Список операторів мобільного зв'язку.	false
`country_name`	string	Назва країни англійською мовою.	false
`country_code`	string(2)	Двобуквений код країни ISO.	false
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний MCCMNC (комбінація коду мобільної країни та коду мобільної мережі), що ідентифікує оператора мобільного зв'язку.	false
`mcc`	string(3)	Трисимвольний MCC (код мобільної країни), що представляє країну мережі.	false
`mnc`	string(2\|3)	Дво- або трисимвольний MNC (код мобільної мережі), що представляє конкретного оператора мобільного зв'язку.	false
`brand`	string	Споживчий бренд, під яким працює ця мережа.	true
`operator`	string	Юридична назва оператора мобільного зв'язку.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/price-listзахищено

Цей ендпоінт повертає список країн, де підтримуються лише MNP-запити, а HLR-запити недоступні для цих напрямків.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/mnp-countries'

{
   "countries":[
      "AG",
      "AI",
      "AR",
      "AS",
      "AW",
      "BB",
      "BM",
      ...
      "US",
      "UY",
      "VC",
      "VE",
      "VG",
      "VN"
   ]
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`countries`	string[]	Список двосимвольних ISO-кодів країн.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/mccmncsзахищено

Цей ендпоінт повертає вичерпний список операторів мобільного зв'язку разом з відповідними ідентифікаторами MCCMNC та додатковою контекстною інформацією.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/mccmncs?countrycode=XX'

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`countrycode`	string(2)	Необов'язковий двобуквений код країни ISO, який використовується для фільтрації результатів MCCMNC, повертаючи лише записи, пов'язані з вказаною країною.	null	необов'язково

{
   "items":[
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26201",
         "mcc":"262",
         "mnc":"01 ",
         "brand":"Telekom",
         "operator":"Telekom Deutschland GmbH"
      },
      {
         "country_name":"Germany",
         "country_code":"DE",
         "mccmnc":"26202",
         "mcc":"262",
         "mnc":"02 ",
         "brand":"Vodafone",
         "operator":"Vodafone D2 GmbH"
      }
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`items`	object[]	Список операторів мобільного зв'язку.	false
`country_name`	string	Повна назва країни англійською мовою.	false
`country_code`	string(2)	Двобуквений код країни ISO, що представляє країну мобільного оператора.	false
`mccmnc`	string(5\|6)	П'яти- або шестисимвольний рядок, що представляє MCCMNC, який унікально ідентифікує оператора мобільного зв'язку.	false
`mcc`	string(3)	Трисимвольний код мобільної країни (MCC), який ідентифікує країну, де працює мобільна мережа.	false
`mnc`	string(2\|3)	Дво- або трисимвольний код мобільної мережі (MNC), який визначає мобільну мережу в межах заданого MCC.	false
`brand`	string	Комерційна назва бренду, під яким мережа працює та відома споживачам.	true
`operator`	string	Офіційна назва оператора мобільного зв'язку, зазвичай юридична особа, що керує мережею.	true
`parent_mccmnc`	string(5\|6)	П'яти- або шестисимвольний рядок, що представляє MCCMNC материнського оператора мобільного зв'язку, якщо такий є.	true

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/priceзахищено

Цей ендпоінт повертає ціну для HLR, MNP або NT запиту.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/price?msisdn=+491788735000&route_type=HLR'

Параметри запиту

Ключ	Тип	Опис	За замовчуванням	Обов'язковий
`msisdn`	string	Номер телефону, для якого потрібно отримати ціну. У міжнародному форматі.	null	обов'язковий
`route_type`	string	Тип маршруту, тобто `HLR`, `MNP`, `NT`.	null	обов'язковий
`route`	string(3)	Маршрут, для якого має бути розрахована ціна. За замовчуванням використовується маршрут, визначений автоматичною маршрутизацією.	null	необов'язково

{
   "price":{
      "amount":"0.01000",
      "msisdn":"+491788735000",
      "route_type":"HLR",
      "route":"DV8"
   }
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`price`	object	Об'єкт з деталями ціноутворення.	false
`amount`	string	Сума в EUR.	false
`msisdn`	string	MSISDN, до якого застосовується ця ціна.	false
`route_type`	string(2\|3)	Тип маршруту, до якого застосовується ця ціна.	false
`route`	string(3)	Маршрут, до якого застосовується ця ціна.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/price-listзахищено

Цей ендпоінт повертає тарифи вашого облікового запису.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/price-list'

{
   "pricing":[
      {
         "route":"V11",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0090"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26201",
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":"26203",
         "cns":"4917821",
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"V11",
         "countrycode":"DE",
         "countryname":"Germany",
         "mccmnc":null,
         "cns":null,
         "route_type":"HLR",
         "price":"0.0070"
      },
      {
         "route":"PTX",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MNP",
         "price":"0.00500"
      },
      ...
      {
         "route":"IP1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"MIX",
         "price":"0.01000"
      },
      {
         "route":"LC1",
         "countrycode":null,
         "countryname":null,
         "mccmnc":null,
         "cns":null,
         "route_type":"NT",
         "price":"0.00500"
      }
   ]
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`pricing`	object[]	Список об'єктів з інформацією про тарифи.	false
`route`	string	Маршрут, до якого застосовується цей тариф.	false
`countrycode`	string	Двосимвольний код країни ISO, до якого застосовується цей тариф для відповідного маршруту, якщо є.	true
`countryname`	string	Англійська назва країни, що відповідає коду країни, якщо є.	true
`mccmnc`	string	MCCMNC, до якого застосовується цей тариф для відповідного маршруту, якщо є. Має пріоритет над тарифами на рівні країни.	true
`cns`	string	Префікс набору, до якого застосовується цей тариф для відповідного маршруту, якщо є. Має пріоритет над тарифами на рівні країни та MCCMNC.	true
`route_type`	string	Відповідний тип маршруту, тобто `HLR`, `MNP`, `NT`.	false
`route_type`	string	Відповідна ціна в EUR.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/balanceзахищено

Цей ендпоінт повертає поточний баланс вашого облікового запису, дозволяючи автоматизувати процеси на основі вашого кредитного статусу. Він безперешкодно працює з повідомленнями про низький баланс, які ви можете налаштувати на сторінці платежів.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/balance'

{
    "balance":"1002.90"
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`balance`	string	Ваш поточний баланс облікового запису в EUR. Десяткове значення типу string.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/pingпублічний

Цей ендпоінт надсилає ping-запит до API, забезпечуючи простий спосіб перевірки вашого з'єднання з HLR Lookups API.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/ping'

{
    "success":true
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`success`	boolean	Вказує, що запит було успішно оброблено.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/timeпублічний

Цей ендпоінт повертає мітку часу Unix, що представляє поточний час на сервері HLR Lookups. Використовуйте його для синхронізації годинника вашого сервера під час генерації підпису Digest-Auth для автентифікації, забезпечуючи виправлення будь-яких розбіжностей між часом вашого сервера та часом сервера HLR Lookups.

Запит Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/time'

{
    "time":1525898643
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`time`	integer	Мітка часу Unix, що представляє поточний час сервера HLR Lookups.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

GET/auth-testзахищено

Цей ендпоінт слугує початковим тестом для вашої реалізації Basic-Auth або, бажано, Digest-Auth.

Запит Basic Auth Запит Digest Auth Успішна відповідь Відповідь з помилкою

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Basic: YOUR_API_KEY"

Заголовки запиту

Ключ	Тип	Опис
`X-Basic`	string	SHA256-хеш `YOUR_API_KEY:YOUR_API_SECRET`. Включіть символ двокрапки (:) у хеш.

curl 'https://www.hlr-lookups.com/api/v2/auth-test' \
  -H "X-Digest-Key: YOUR_API_KEY" \
  -H "X-Digest-Signature: DIGEST_AUTH_SIGNATURE" \
  -H "X-Digest-Timestamp: UNIX_TIMESTAMP"

Заголовки запиту

Ключ	Тип	Опис
`X-Digest-Key`	string	Ваш API ключ HLR Lookups
`X-Digest-Signature`	string	Унікальний підпис Digest-Auth (див. автентифікація)
`X-Digest-Timestamp`	integer	Поточна мітка часу Unix (також див. `GET /time`)

{
    "success":true
}

Атрибути успішної відповіді

Ім'я	Тип	Опис	Необов'язковий
`success`	boolean	Вказує, що запит було успішно оброблено.	false

{
    "errors":[
        "Service unavailable."
    ]
}

Параметри відповіді про помилку

Ім'я	Тип	Опис	Необов'язковий
`errors[]`	string[]	Список рядків з поясненням помилки.	false

Прокрутити вгору

Документація застарілого API

Зверніть увагу, що застаріле API більше не підтримується і буде виведено з експлуатації в майбутньому. Ми наполегливо рекомендуємо перейти на останню версію найближчим часом.

Якщо ви впровадили наш HLR Lookups API між 2013 та початком 2020 року, ви використовуєте застаріле API. У такому разі зверніться до нашої документації застарілого API.

Документація застарілого API

Документація API

Початок роботи

HLR-перевірки

MNP-перевірки

NT-перевірки

Маршрутизація

Ціноутворення

Інструменти

Початок роботи

Використання API HLR Lookups

Приклад запиту

Приклад payload

Успішна відповідь application/json

Додаткові сервіси перевірки

Перевірка переносимості мобільних номерів (MNP)

Визначення типу номера (NT)

Комплекти розробки програмного забезпечення (SDK)

Інструменти

Не розробник?

Автентифікація

API-ключ та API-секрет

HTTP Basic Auth

Рекомендовано: X-Basic заголовок з SHA256

Запит Basic Auth

Заголовки базової автентифікації

Приклад коду

Приклад запиту

Заголовки запиту

Формування підпису

Компоненти Digest-підпису

Приклади коду

Концепції

Синхронний API HLR-запитів

Асинхронний API HLR-запитів

SDK (комплекти для розробки програмного забезпечення)

SDK для PHP

SDK для NodeJS

SDK для Ruby

POST/hlr-lookupзахищено

Дані запиту

Параметри запиту

Атрибути успішної відповіді

Параметри відповіді про помилку

POST/hlr-lookupsзахищено

Дані запиту

Параметри запиту

Атрибути успішної відповіді

Параметри відповіді про помилку

Обробка вебхуків

Автентифікація

Приклад коду

Підтвердження отримання

Дані вебхука

Атрибути payload вебхука

POST/mnp-lookupзахищено

Дані запиту

Параметри запиту

Атрибути успішної відповіді

Параметри відповіді про помилку

POST/mnp-lookupsзахищено

Дані запиту

Параметри запиту

Атрибути успішної відповіді

Параметри відповіді про помилку

Обробка вебхуків

Автентифікація

Приклад коду

Підтвердження отримання

Дані вебхука

Атрибути payload вебхука

POST/nt-lookupзахищено

Дані запиту

Параметри запиту

Атрибути успішної відповіді

Параметри відповіді про помилку

POST/nt-lookups захищено

Дані запиту

Параметри запиту

Атрибути успішної відповіді

Параметри відповіді про помилку