Guida Introduttiva

L'infrastruttura della rete mobile globale opera su un sistema noto come rete di segnalazione SS7. Questa rete facilita lo scambio di dati degli abbonati, l'instradamento delle chiamate, la trasmissione di SMS e gli aggiornamenti in tempo reale sullo stato di connettività mobile tra gli operatori. Ogni rete mobile mantiene un Home Location Register (HLR), un database centrale che memorizza i dettagli essenziali dei propri abbonati.

La tecnologia HLR Lookup consente alle aziende di interrogare questi registri e recuperare in tempo reale i dettagli di connettività e rete per qualsiasi numero di telefono mobile. Ciò include informazioni su se il telefono è acceso, a quale rete è attualmente assegnato, se è stato portato, se il numero è valido o disattivato e se è in roaming.

L'API HLR Lookups fornisce un accesso immediato e continuo a questi dati, consentendo alle aziende di verificare i numeri mobili, ottimizzare l'instradamento e migliorare le comunicazioni con i clienti. Questa documentazione ti guiderà nell'integrazione di HLR Lookups nel tuo software, abilitando il recupero automatizzato di informazioni mobili in tempo reale.

Utilizzo dell'API HLR Lookups

L'esecuzione di interrogazioni HLR Lookup è veloce, sicura e semplice. Una volta effettuata la registrazione e ottenuta la tua chiave API, puoi autenticarti e avviare ricerche istantanee con semplici richieste HTTP POST, tramite POST /hlr-lookup. In alternativa, puoi elaborare grandi set di dati optando per richieste API asincrone veloci con risultati inviati al tuo server tramite webhook, come spiegato nella sezione concetti.

Richiesta di Esempio

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"

L'autenticazione viene fornita tramite intestazioni HTTP e payload.json dovrebbe contenere (come minimo) il seguente oggetto JSON:

Payload di Esempio

{
   "msisdn": "+14156226819"
}

Al termine dell'esecuzione, riceverai una risposta contenente i dettagli di connettività in tempo reale per il numero mobile specificato.

Risposta di Successo 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"
}

Per una descrizione completa degli attributi di richiesta e risposta e degli stati di connettività, consulta POST /hlr-lookup.

Servizi di Ricerca Aggiuntivi

Ricerche di Portabilità del Numero Mobile (MNP)

Utilizza le ricerche MNP per determinare la proprietà della rete e i dettagli di portabilità senza interrogare la connettività in tempo reale. Se hai bisogno solo del MCCMNC di un numero, consulta POST /mnp-lookup.

Ricerche di Rilevamento del Tipo di Numero (NT)

Determina se un numero di telefono appartiene a una rete fissa, mobile, a tariffazione premium, VoIP, cercapersone o altri intervalli del piano di numerazione con POST /nt-lookup.

Kit di Sviluppo Software (SDK)

L'API HLR Lookups funziona con qualsiasi client REST in qualsiasi linguaggio di programmazione e abbiamo pubblicato SDK per PHP, Ruby e NodeJS sul nostro GitHub per aiutarti a iniziare rapidamente.

Strumenti

Per garantire un'esperienza di sviluppo fluida, offriamo una suite completa di strumenti, tra cui monitoraggio delle richieste API e webhook nel browser, whitelist degli indirizzi IP, robuste opzioni di autenticazione e un endpoint di test per l'autenticazione.

Non Sei uno Sviluppatore?

Le ricerche HLR e le interrogazioni di portabilità del numero possono essere eseguite senza alcuna programmazione. Scopri di più sul nostro client web aziendale e sulle funzionalità di reportistica basate su browser.

Autenticazione

Per garantire la sicurezza e un corretto controllo degli accessi, la maggior parte delle richieste all'API HLR Lookups richiede l'autenticazione. Gli endpoint sono classificati come pubblici o protetti. Quando si accede a un endpoint protetto, la richiesta deve essere autenticata utilizzando la chiave API e il secret tramite il metodo Digest-Auth o Basic-Auth. Digest-Auth è l'opzione più sicura ed è fortemente consigliata. Utilizzare l'endpoint GET /auth-test per verificare la configurazione dell'autenticazione.

Chiave API e Secret API

Ottenere la chiave API e il secret dalla pagina Impostazioni API. È inoltre possibile configurare il metodo di autenticazione preferito e abilitare la whitelist degli indirizzi IP per una maggiore sicurezza. Se si sospetta che il secret API sia stato compromesso, è possibile generarne uno nuovo in qualsiasi momento.

Basic Auth Digest Auth Whitelist IP

L'autenticazione Basic standard è facile da implementare e ampiamente supportata. È possibile autenticarsi passando la chiave API e il secret come coppia user:pass nella richiesta HTTP.

HTTP Basic Auth

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

Questo invia un header Authorization:

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Consigliato: Header X-Basic con SHA256

Per una maggiore sicurezza, è possibile inviare un hash SHA256 delle credenziali invece di trasmetterle direttamente in base64. Per utilizzare questo metodo, calcolare l'hash della coppia YOUR_API_KEY:YOUR_API_SECRET e inviarlo tramite l'header X-Basic:

Richiesta Basic Auth

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

Header di Autenticazione Basic

Chiave	Tipo	Descrizione
`X-Basic`	string	Hash SHA256 di `YOUR_API_KEY:YOUR_API_SECRET`. Includere il simbolo dei due punti (:) nell'hash.	obbligatorio

Esempio di Codice

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

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

Digest-Auth è il metodo consigliato per proteggere l'accesso agli endpoint protetti dell'API HLR Lookup. Ogni richiesta deve includere i seguenti header: X-Digest-Key, X-Digest-Signature e X-Digest-Timestamp, che sono spiegati di seguito.

Esempio di Richiesta

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"

Header della Richiesta

Chiave	Tipo	Descrizione
`X-Digest-Key`	string	La chiave API univoca di HLR Lookups.	obbligatorio
`X-Digest-Signature`	string	Una firma di autenticazione univoca (vedere di seguito).	obbligatorio
`X-Digest-Timestamp`	integer	Timestamp Unix corrente (vedere anche `GET /time`).	obbligatorio

Costruzione della Firma

La X-Digest-Signature viene creata utilizzando un hash HMAC SHA256, con il secret API come chiave condivisa.

La stringa da sottoporre a hash è strutturata come segue:

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Il simbolo . rappresenta la concatenazione di stringhe.

Componenti della Firma Digest

Componente	Tipo	Descrizione
`ENDPOINT_PATH`	string	L'endpoint API richiesto, ad esempio `/auth-test` in minuscolo.
`UNIX_TIMESTAMP`	integer	Timestamp Unix corrente (deve essere entro 30 secondi). Vedere `GET /time`.
`REQUEST_METHOD`	string	Il metodo HTTP utilizzato, ad esempio `POST` o `GET`.
`REQUEST_BODY`	string	Dati del corpo della richiesta. Impostare su `null` per le richieste `GET`.

Esempi di Codice

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)

Scorri Su

Concetti

Implementare le interrogazioni HLR in qualsiasi linguaggio di programmazione o sistema tramite la nostra API HTTP REST è semplice ed efficiente. Con un processo di integrazione semplice, è possibile iniziare a interrogare le reti mobili in tempo reale per ottenere informazioni immediate sulla validità dei numeri di telefono, lo stato di connettività e i dettagli di instradamento.

La scelta dell'API appropriata dipende dal caso d'uso specifico. Se si necessita di risultati di interrogazione in tempo reale per applicazioni come telefonia VoIP, rilevamento frodi o instradamento SMS, l'API sincrona rappresenta la scelta migliore. Tuttavia, se il caso d'uso prevede elaborazione ad alto volume, interrogazioni massive o verifica dati su larga scala, l'API asincrona offre prestazioni ottimizzate con efficienza di banda e capacità di interrogazione in batch.

Configurare l'API per utilizzare una delle nostre opzioni di instradamento personalizzate per ottimizzare velocità, accuratezza ed efficienza dei costi. È inoltre possibile memorizzare i risultati delle interrogazioni negli archivi per scaricare facilmente report in formato CSV e JSON, nonché per analisi avanzate tramite l'interfaccia web.

API di interrogazione HLR sincrona

L'endpoint POST /hlr-lookup elabora un numero di telefono mobile (MSISDN) per richiesta e restituisce i risultati istantaneamente nel corpo della risposta HTTP. I risultati sono formattati in JSON e sono ideali per applicazioni in tempo reale, tra cui validazione di numeri mobili, instradamento chiamate e consegna messaggi SMS.

Una chiamata API sincrona consiste in una richiesta e risposta HTTP diretta. Il sistema invia un singolo MSISDN (numero mobile) per richiesta e riceve una risposta immediata contenente i risultati dell'interrogazione HLR in tempo reale in formato JSON. Questa API è ottimizzata per casi d'uso che richiedono verifica istantanea e controlli di connettività, come rilevamento frodi, instradamento chiamate VoIP e ottimizzazione gateway SMS.

API HLR Lookup Asincrona

L'endpoint POST /hlr-lookups è progettato per l'elaborazione massiva e ad alto volume, consentendo di inviare fino a 1,000 MSISDN per richiesta. Anziché restituire i risultati istantaneamente, questa API utilizza webhook automatizzati per inviare progressivamente i risultati al server. I risultati delle interrogazioni vengono restituiti come oggetti JSON tramite callback HTTP POST.

L'API asincrona è ottimizzata per velocità, efficienza e scalabilità. Elimina i problemi di latenza di rete associati alle chiamate sincrone, rendendola ideale per le aziende che necessitano di interrogazioni ad alta capacità. Il sistema invia fino a 1,000 MSISDN per richiesta e la nostra piattaforma li elabora in parallelo, restituendo i risultati al server tramite webhook HTTP in batch fino a 1,000 risultati per callback.

SDK (Software Development Kit)

I nostri Software Development Kit (SDK) per PHP, NodeJS e Ruby semplificano il processo di integrazione, consentendovi di connettervi all'API HLR Lookups in modo efficiente e con il minimo sforzo.

Questi SDK forniscono funzioni predefinite, gestione dell'autenticazione e modelli strutturati di richieste API, riducendo i tempi di sviluppo e garantendo le migliori pratiche.

Esplorate l'elenco completo degli SDK disponibili su GitHub e iniziate a integrare oggi stesso.

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);

Visualizza su 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   }

Visualizza su 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)

Visualizza su GitHub README.md

Scorri Su

POST/hlr-lookupprotetto

Esegue una ricerca HLR sincrona, fornendo dati in tempo reale sulla connettività e portabilità dei numeri di telefonia mobile direttamente dagli operatori di rete. Questo endpoint è ideale per scenari di traffico live in cui applicazioni time-sensitive richiedono una verifica immediata per stabilire se un numero di telefono è attualmente raggiungibile (connesso) o non disponibile (spento). Inoltre, aiuta a distinguere i numeri attivi da quelli non validi, sconosciuti o falsi.

Per l'elaborazione massiva di grandi dataset che non richiedono risultati istantanei, si consiglia di utilizzare l'endpoint asincrono POST /hlr-lookups, ottimizzato per l'elaborazione batch ad alta velocità.

Se l'obiettivo principale è recuperare i dati di portabilità del numero mobile (MCCMNC) senza necessità dello stato di connettività live, l'endpoint POST /mnp-lookup offre un'alternativa economicamente vantaggiosa per le query di portabilità dei numeri mobili.

Richiesta Risposta di Successo Risposta di Errore Riferimento Stati

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

Payload

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`msisdn`	string	Il numero di telefono mobile (MSISDN) da interrogare, fornito in formato internazionale (es. +14156226819 o 0014156226819). I prefissi internazionali sono obbligatori.	null	obbligatorio
`route`	string(3)	Un identificatore opzionale di tre caratteri che specifica il percorso per questa ricerca. Impostare su `null` o omettere questo parametro per applicare la mappa di routing personalizzata o consentire al sistema di determinare automaticamente il percorso ottimale per questa ricerca.	null	facoltativo
`storage`	string	Un identificatore di archiviazione opzionale che specifica il report in cui verranno memorizzati i risultati per revisione manuale, analisi e reporting. Il sistema aggiunge automaticamente un timestamp con il mese corrente. Se omesso o impostato su `null`, il sistema raggrupperà automaticamente i risultati per mese a scopo di reporting.	null	facoltativo

{
   "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"
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`id`	string(12)	Un identificatore univoco assegnato a questa richiesta di lookup.	false
`msisdn`	string	Il numero di telefono mobile interrogato, formattato in formato internazionale (es. +14156226819 o 0014156226819).	false
`connectivity_status`	string	Indica se lo stato di connettività del numero è stato recuperato con successo. Valori possibili: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` o `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Un Mobile Country Code (MCC) e Mobile Network Code (MNC) di cinque o sei cifre che identificano la rete attualmente associata al numero di telefono.	true
`mcc`	string(3)	Un Mobile Country Code (MCC) di tre cifre che identifica il paese in cui il numero di telefono è registrato.	true
`mnc`	string(2\|3)	Un Mobile Network Code (MNC) di due o tre cifre che identifica la rete specifica a cui appartiene il numero di telefono.	true
`imsi`	string	L'International Mobile Subscriber Identity (IMSI), un identificatore univoco per la scheda SIM associata a questo numero. La disponibilità dipende dalla configurazione della rete.	true
`msin`	string(10)	Il Mobile Subscription Identification Number (MSIN) all'interno del database dell'operatore mobile. La disponibilità dipende dalla configurazione della rete.	true
`msc`	string(12)	Il Mobile Switching Center (MSC) che attualmente gestisce le comunicazioni di questo abbonato. La disponibilità dipende dalla configurazione della rete.	true
`original_network_name`	string	Il nome dell'operatore di rete originale (nativo) associato a questo numero.	true
`original_country_name`	string	Il nome completo del paese in cui il numero di telefono mobile è stato originariamente registrato, fornito in inglese.	true
`original_country_code`	string(2)	Il codice paese ISO di due caratteri che rappresenta il paese in cui il numero di telefono è stato assegnato per la prima volta.	true
`original_country_prefix`	string	Il prefisso internazionale (country calling code) corrispondente al paese di origine del numero di telefono mobile.	true
`is_ported`	boolean	Indica se il numero mobile è stato portato dalla rete originale a un operatore diverso.	true
`ported_network_name`	string	Il nome dell'operatore di rete a cui il numero mobile è stato portato, se applicabile.	true
`ported_country_name`	string	Il nome del paese in cui il numero mobile è stato portato, se applicabile.	true
`ported_country_code`	string(2)	Il codice paese ISO di due caratteri che rappresenta il paese in cui il numero mobile è stato portato, se applicabile.	true
`ported_country_prefix`	string	Il prefisso internazionale (country calling code) per il paese in cui il numero mobile è stato portato, se applicabile.	true
`is_roaming`	boolean	Indica se il numero mobile è attualmente in roaming su una rete estera. La disponibilità dello stato di roaming dipende dall'operatore di rete mobile.	true
`roaming_network_name`	string	Il nome della rete su cui il numero mobile è attualmente in roaming, se applicabile.	true
`roaming_country_name`	string	Il nome del paese in cui il numero mobile è attualmente in roaming, se applicabile.	true
`roaming_country_code`	string(2)	Il codice paese ISO di due caratteri del paese in cui il numero mobile è attualmente in roaming, se applicabile.	true
`roaming_country_prefix`	string	Il prefisso internazionale (country calling code) del paese in cui il numero mobile è attualmente in roaming, se applicabile.	true
`cost`	string	Un valore decimale rappresentato come stringa, che indica il costo del lookup in EUR.	true
`timestamp`	string	Un timestamp formattato W3C che include il fuso orario, specificando quando il lookup è stato completato.	true
`storage`	string	Il nome dell'archivio in cui sono stati salvati i risultati del lookup. Corrisponde ai nomi dei report e ai download CSV disponibili tramite l'interfaccia web.	true
`route`	string(3)	Un identificatore di tre caratteri che indica il metodo di routing utilizzato per questa richiesta di lookup.	true
`processing_status`	string	L'esito dell'elaborazione del lookup. Valori possibili: `COMPLETED` (riuscito), `REJECTED` (rete non raggiungibile, nessun addebito applicato) o `FAILED` (errore verificatosi durante l'elaborazione).	false
`error_code`	integer	Un codice di errore interno opzionale che fornisce informazioni diagnostiche aggiuntive per l'assistenza clienti.	true
`error_description`	string	Una breve spiegazione del codice di errore fornito (se presente) in testo semplice inglese.	true
`data_source`	string	La fonte dati utilizzata per questa richiesta. Valori possibili: `LIVE_HLR` (interrogazione HLR in tempo reale) o `MNP_DB` (database statico di portabilità del numero mobile). Consultare le opzioni di routing per i dettagli.	false
`routing_instruction`	string	Una stringa delimitata da due punti che descrive l'istruzione di routing utilizzata nella richiesta. Il primo componente è `STATIC` quando si specifica un percorso o `AUTO` per il routing automatico; il secondo componente è l'identificatore del percorso e per le richieste di routing automatico un terzo componente mostra l'origine su cui si basa la decisione di routing (cioè `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."
    ]
}

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Stato	Descrizione
CONNECTED	Il numero è valido e il dispositivo di destinazione è attualmente connesso alla rete mobile. Chiamate, SMS e altri servizi dovrebbero raggiungere il destinatario con successo.
ABSENT	Il numero è valido, ma il dispositivo di destinazione è spento o temporaneamente fuori dalla copertura di rete. Messaggi o chiamate potrebbero non essere recapitati fino a quando il dispositivo non si riconnette alla rete.
INVALID_MSISDN	Il numero non è valido o non è attualmente assegnato ad alcun abbonato sulla rete mobile. Chiamate e messaggi a questo numero non andranno a buon fine.
UNDETERMINED	Non è stato possibile determinare lo stato di connettività del numero. Ciò potrebbe essere dovuto a un numero non valido, a una risposta di errore SS7 o a una mancanza di connettività con l'operatore di rete di destinazione. Verificare il codice di errore e il relativo campo descrittivo per ulteriori informazioni diagnostiche.

Scorri Su

POST/hlr-lookupsprotetto

Avvia un batch di lookup HLR asincroni, recuperando dati in tempo reale sulla connettività e portabilità dei numeri di telefonia mobile dagli operatori di rete. I risultati vengono consegnati tramite webhook al tuo server. Questo metodo è ottimizzato per l'elaborazione di grandi volumi di numeri che non richiedono risposte immediate, come la pulizia e verifica dei database. Per applicazioni in tempo reale come l'instradamento delle chiamate o la consegna di SMS, considera l'utilizzo dell'endpoint POST /hlr-lookup.

Questo endpoint è ideale per l'elaborazione in blocco quando l'obiettivo è identificare i numeri di telefono attualmente raggiungibili (connessi) o non disponibili (telefono spento) filtrando numeri non validi, non assegnati o falsi. Inoltre, fornisce lo stato di portabilità in tempo reale (MCCMNC) insieme ai dettagli di connettività.

Prima di utilizzare questo endpoint, assicurati che sia configurato un URL webhook per ricevere i risultati dei lookup in modo asincrono. Puoi configurarlo nelle tue impostazioni API.

Richiesta Risposta di Successo Risposta di Errore Webhook Riferimento Stati

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

Payload

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`msisdns`	array	Un array di numeri di telefonia mobile (MSISDN) in formato internazionale (es. +14156226819 o 0014156226819). Puoi includere fino a 1000 numeri per richiesta.	null	obbligatorio
`route`	string(3)	Un identificatore opzionale di tre caratteri che specifica il percorso per questa ricerca. Impostare su `null` o omettere questo parametro per applicare la mappa di routing personalizzata o consentire al sistema di determinare automaticamente il percorso ottimale per questa ricerca.	null	facoltativo
`storage`	string	Un identificatore di archiviazione opzionale che specifica il report in cui verranno memorizzati i risultati per revisione manuale, analisi e reporting. Il sistema aggiunge automaticamente un timestamp con il mese corrente. Se omesso o impostato su `null`, il sistema raggrupperà automaticamente i risultati per mese a scopo di reporting.	null	facoltativo

{
   "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"
   ]
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`accepted`	array	Un elenco di oggetti contenenti identificatori univoci e MSISDN che sono stati accettati per l'elaborazione.	false
`accepted_count`	integer	Il numero totale di MSISDN accettati con successo per l'elaborazione.	false
`rejected`	array	Un elenco di oggetti contenenti identificatori univoci e MSISDN che sono stati rifiutati per l'elaborazione, tipicamente a causa di numeri non validi. Nessun addebito viene applicato per le voci rifiutate.	false
`rejected_count`	integer	Il numero totale di MSISDN rifiutati a causa di errori di validazione.	false
`total_count`	integer	Il conteggio totale di MSISDN accettati e rifiutati che sono stati inviati per l'elaborazione.	false
`cost`	string	Un valore decimale rappresentato come stringa, che indica il costo totale in EUR per i lookup accettati.	false
`storage`	string	Il nome dello storage dove vengono aggiunti i risultati dei lookup, utilizzato per il reporting e i download CSV tramite l'interfaccia web.	false
`route`	string(3\|4)	Un identificatore di tre o quattro caratteri che specifica il percorso utilizzato per questa richiesta di lookup. Contiene AUTO se è stato richiesto l'instradamento automatico basato sul numero.	false
`webhook_urls`	array	Gli URL webhook configurati nelle tue impostazioni API. I risultati vengono inviati qui.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Elaborazione Webhook

Una volta inviati, la nostra piattaforma inizia a elaborare i numeri di telefono forniti e invia i risultati all'URL webhook precedentemente specificato sul vostro server. I risultati vengono trasmessi come richiesta HTTP POST con un oggetto JSON nel corpo della richiesta.

Autenticazione

Autenticare il webhook ispezionando l'intestazione HTTP X-Signatures.

L'intestazione X-Signatures contiene un elenco di firme separate da punto e virgola. Ogni firma nell'elenco viene generata utilizzando uno dei secret API configurati nel vostro account. Per verificare il webhook, generare un hash SHA-256 utilizzando la chiave API, il secret e il corpo HTTP grezzo, quindi confrontarlo con le firme nell'elenco.

Una corrispondenza conferma che la richiesta è autentica e firmata con un secret sotto il vostro controllo.

Esempio di Codice

$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;
    }
}

La richiesta è valida se una qualsiasi delle firme fornite nell'intestazione corrisponde a un hash SHA256 calcolato sulla stringa concatenata della chiave API, del secret e del corpo HTTP.

Conferma di Ricezione

Il vostro server deve rispondere con un codice di stato HTTP 200 OK per confermare la ricezione avvenuta con successo. Se viene restituito un altro codice di risposta, si verifica un timeout (10 secondi) o si presenta qualsiasi altro problema di consegna, il sistema ritenterà automaticamente l'invio del webhook dopo un minuto. Se la richiesta continua a fallire, i tentativi seguiranno una strategia di backoff esponenziale, con successivi tentativi dopo 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuti.

Questo meccanismo di retry garantisce la massima affidabilità nella consegna dei risultati di lookup alla vostra infrastruttura. Riduce al minimo il rischio di perdita di dati dovuta a problemi di rete temporanei o interruzioni del server.

Payload Webhook

{
   "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"
      }
   ]
}

Attributi del Payload Webhook

L'oggetto JSON contiene un attributo type => HLR insieme a un attributo results che include un elenco di oggetti lookup, come documentato di seguito.

Nome	Tipo	Descrizione	Nullable
`id`	string(12)	Un identificatore univoco assegnato a questa richiesta di lookup.	false
`msisdn`	string	Il numero di telefono mobile interrogato, formattato in formato internazionale (es. +14156226819 o 0014156226819).	false
`connectivity_status`	string	Indica se lo stato di connettività del numero è stato recuperato con successo. Valori possibili: `CONNECTED` , `ABSENT` , `INVALID_MSISDN` o `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Un Mobile Country Code (MCC) e Mobile Network Code (MNC) di cinque o sei cifre che identificano la rete attualmente associata al numero di telefono.	true
`mcc`	string(3)	Un Mobile Country Code (MCC) di tre cifre che identifica il paese in cui il numero di telefono è registrato.	true
`mnc`	string(2\|3)	Un Mobile Network Code (MNC) di due o tre cifre che identifica la rete specifica a cui appartiene il numero di telefono.	true
`imsi`	string	L'International Mobile Subscriber Identity (IMSI), un identificatore univoco per la scheda SIM associata a questo numero. La disponibilità dipende dalla configurazione della rete.	true
`msin`	string(10)	Il Mobile Subscription Identification Number (MSIN) all'interno del database dell'operatore mobile. La disponibilità dipende dalla configurazione della rete.	true
`msc`	string(12)	Il Mobile Switching Center (MSC) che attualmente gestisce le comunicazioni di questo abbonato. La disponibilità dipende dalla configurazione della rete.	true
`original_network_name`	string	Il nome dell'operatore di rete originale (nativo) associato a questo numero.	true
`original_country_name`	string	Il nome completo del paese in cui il numero di telefono mobile è stato originariamente registrato, fornito in inglese.	true
`original_country_code`	string(2)	Il codice paese ISO di due caratteri che rappresenta il paese in cui il numero di telefono è stato assegnato per la prima volta.	true
`original_country_prefix`	string	Il prefisso internazionale (country calling code) corrispondente al paese di origine del numero di telefono mobile.	true
`is_ported`	boolean	Indica se il numero mobile è stato portato dalla rete originale a un operatore diverso.	true
`ported_network_name`	string	Il nome dell'operatore di rete a cui il numero mobile è stato portato, se applicabile.	true
`ported_country_name`	string	Il nome del paese in cui il numero mobile è stato portato, se applicabile.	true
`ported_country_code`	string(2)	Il codice paese ISO di due caratteri che rappresenta il paese in cui il numero mobile è stato portato, se applicabile.	true
`ported_country_prefix`	string	Il prefisso internazionale (country calling code) per il paese in cui il numero mobile è stato portato, se applicabile.	true
`is_roaming`	boolean	Indica se il numero mobile è attualmente in roaming su una rete estera. La disponibilità dello stato di roaming dipende dall'operatore di rete mobile.	true
`roaming_network_name`	string	Il nome della rete su cui il numero mobile è attualmente in roaming, se applicabile.	true
`roaming_country_name`	string	Il nome del paese in cui il numero mobile è attualmente in roaming, se applicabile.	true
`roaming_country_code`	string(2)	Il codice paese ISO di due caratteri del paese in cui il numero mobile è attualmente in roaming, se applicabile.	true
`roaming_country_prefix`	string	Il prefisso internazionale (country calling code) del paese in cui il numero mobile è attualmente in roaming, se applicabile.	true
`cost`	string	Un valore decimale rappresentato come stringa, che indica il costo del lookup in EUR.	true
`timestamp`	string	Un timestamp formattato W3C che include il fuso orario, specificando quando il lookup è stato completato.	true
`storage`	string	Il nome dell'archivio in cui sono stati salvati i risultati del lookup. Corrisponde ai nomi dei report e ai download CSV disponibili tramite l'interfaccia web.	true
`route`	string(3)	Un identificatore di tre caratteri che indica il metodo di routing utilizzato per questa richiesta di lookup.	true
`processing_status`	string	L'esito dell'elaborazione del lookup. Valori possibili: `COMPLETED` (riuscito), `REJECTED` (rete non raggiungibile, nessun addebito applicato) o `FAILED` (errore verificatosi durante l'elaborazione).	false
`error_code`	integer	Un codice di errore interno opzionale che fornisce informazioni diagnostiche aggiuntive per l'assistenza clienti.	true
`error_description`	string	Una breve spiegazione del codice di errore fornito (se presente) in testo semplice inglese.	true
`data_source`	string	La fonte dati utilizzata per questa richiesta. Valori possibili: `LIVE_HLR` (interrogazione HLR in tempo reale) o `MNP_DB` (database statico di portabilità del numero mobile). Consultare le opzioni di routing per i dettagli.	false
`routing_instruction`	string	Una stringa delimitata da due punti che descrive l'istruzione di routing utilizzata nella richiesta. Il primo componente è `STATIC` quando si specifica un percorso o `AUTO` per il routing automatico; il secondo componente è l'identificatore del percorso e per le richieste di routing automatico un terzo componente mostra l'origine su cui si basa la decisione di routing (cioè `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

Stato	Descrizione
CONNECTED	Il numero è valido e il dispositivo di destinazione è attualmente connesso alla rete mobile. Chiamate, SMS e altri servizi dovrebbero raggiungere il destinatario con successo.
ABSENT	Il numero è valido, ma il dispositivo di destinazione è spento o temporaneamente fuori dalla copertura di rete. Messaggi o chiamate potrebbero non essere recapitati fino a quando il dispositivo non si riconnette alla rete.
INVALID_MSISDN	Il numero non è valido o non è attualmente assegnato ad alcun abbonato sulla rete mobile. Chiamate e messaggi a questo numero non andranno a buon fine.
UNDETERMINED	Non è stato possibile determinare lo stato di connettività del numero. Ciò potrebbe essere dovuto a un numero non valido, a una risposta di errore SS7 o a una mancanza di connettività con l'operatore di rete di destinazione. Verificare il codice di errore e il relativo campo descrittivo per ulteriori informazioni diagnostiche.

Scorri Su

POST/mnp-lookupprotetto

Esegue una ricerca MNP sincrona e fornisce informazioni sulla portabilità del numero mobile e sulla rete. Questo endpoint è ideale se il vostro obiettivo principale è estrarre l'MCCMNC corrente di un determinato numero di telefono mobile e individuare le reti originale e corrente in tempo reale.

Per l'elaborazione massiva di grandi dataset che non richiedono risultati istantanei, si consiglia di utilizzare l'endpoint asincrono POST /mnp-lookups, ottimizzato per l'elaborazione batch ad alta velocità.

Le query MNP determinano in modo affidabile la portabilità e le informazioni di rete, ma non indicano se il telefono mobile di destinazione è attualmente connesso a una rete e raggiungibile. Per estrarre informazioni sulla connettività in tempo reale, utilizzare invece l'endpoint POST /hlr-lookup.

Richiesta Risposta di Successo Risposta di Errore

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

Payload

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`msisdn`	string	Il numero di telefono mobile (MSISDN) da interrogare, fornito in formato internazionale (es. +14156226819 o 0014156226819). I prefissi internazionali sono obbligatori.	null	obbligatorio
`route`	string(3)	Un identificatore opzionale di tre caratteri che specifica il percorso per questa ricerca. Impostare su `null` o omettere questo parametro per applicare la mappa di routing personalizzata o consentire al sistema di determinare automaticamente il percorso ottimale per questa ricerca.	null	facoltativo
`storage`	string	Un identificatore di archiviazione opzionale che specifica il report in cui verranno memorizzati i risultati per revisione manuale, analisi e reporting. Il sistema aggiunge automaticamente un timestamp con il mese corrente. Se omesso o impostato su `null`, il sistema raggrupperà automaticamente i risultati per mese a scopo di reporting.	null	facoltativo

{
   "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
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`id`	string(12)	Un identificativo univoco di 12 caratteri per questa interrogazione.	false
`msisdn`	string	Il numero di telefono mobile valutato in questa richiesta di interrogazione.	false
`query_status`	string	Indica se il recupero delle informazioni di portabilità e di rete è avvenuto con successo. I valori possibili sono `OK` o `FAILED`.	false
`mccmnc`	string(5\|6)	Un codice MCCMNC di cinque o sei caratteri (tupla di mobile country code e mobile network code) che identifica la rete a cui appartiene attualmente il numero di telefono mobile.	true
`mcc`	string(3)	Un MCC di tre caratteri (mobile country code) che rappresenta il paese associato alla rete attuale del numero di telefono mobile.	true
`mnc`	string(2\|3)	Un MNC di due o tre caratteri (mobile network code) che identifica l'operatore di rete attuale per il numero di telefono mobile.	true
`is_ported`	boolean	Indica se il numero di telefono è stato portato dalla rete originale a un nuovo operatore.	true
`original_network_name`	string	Una stringa arbitraria (in inglese) che specifica il nome dell'operatore di rete originale del numero di telefono mobile ispezionato.	true
`original_country_name`	string	Una stringa arbitraria (in inglese) che indica il paese originale del numero di telefono mobile ispezionato.	true
`original_country_code`	string(2)	Un codice paese ISO di due caratteri che rappresenta il paese originale del numero di telefono mobile ispezionato.	true
`original_country_prefix`	string	Il prefisso internazionale del paese originale associato al numero di telefono mobile ispezionato.	true
`ported_network_name`	string	Specifica l'operatore di rete a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`ported_country_name`	string	Specifica il paese a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`ported_country_code`	string(2)	Un codice paese ISO di due caratteri che rappresenta il paese a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`ported_country_prefix`	string	Il prefisso internazionale del paese a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`extra`	string	Una stringa arbitraria che fornisce dettagli aggiuntivi opzionali sul numero di telefono.	true
`cost`	string	Un valore decimale, rappresentato come stringa, che indica il costo in EUR per questa interrogazione.	true
`timestamp`	string	Un timestamp in formato W3C, comprensivo di informazioni sul fuso orario, che indica quando l'interrogazione è stata completata.	true
`storage`	string	Il nome di archiviazione (o nome del report) a cui sono stati aggiunti i risultati dell'interrogazione. Viene utilizzato per i download CSV e i report tramite l'interfaccia web.	true
`route`	string(3)	Un identificativo di tre caratteri che specifica il percorso utilizzato per questa richiesta di interrogazione.	true
`error_code`	integer	Un codice di errore interno opzionale che fornisce contesto aggiuntivo per la diagnostica dell'assistenza clienti.	true

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

POST/mnp-lookupsprotetto

Avvia un batch di lookup MNP (mobile number portability) asincroni, recuperando l'MCCMNC corrente e identificando in tempo reale le reti originali e attuali. I risultati vengono consegnati tramite webhook al tuo server. Questo metodo è ottimizzato per l'elaborazione di grandi volumi di numeri che non richiedono risposte immediate, come la pulizia e verifica dei database. Per applicazioni in tempo reale come l'instradamento delle chiamate o la consegna di SMS, considera l'utilizzo dell'endpoint POST /mnp-lookup.

Le query MNP determinano in modo affidabile la portabilità e le informazioni di rete, ma non indicano se il telefono mobile di destinazione è attualmente connesso a una rete e raggiungibile. Per estrarre informazioni sulla connettività in tempo reale, utilizzare invece l'endpoint POST /hlr-lookups.

Prima di utilizzare questo endpoint, assicurati che sia configurato un URL webhook per ricevere i risultati dei lookup in modo asincrono. Puoi configurarlo nelle tue impostazioni API.

Richiesta Risposta di Successo Risposta di Errore Webhook

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

Payload

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`msisdns`	array	Un array di numeri di telefonia mobile (MSISDN) in formato internazionale (es. +14156226819 o 0014156226819). Puoi includere fino a 1000 numeri per richiesta.	null	obbligatorio
`route`	string(3)	Un identificatore opzionale di tre caratteri che specifica il percorso per questo lookup. Impostare su `null` o omettere questo parametro per applicare la tua mappa di routing personalizzata o lasciare che il nostro sistema determini automaticamente i percorsi migliori per questa richiesta.	null	facoltativo
`storage`	string	Un identificatore di archiviazione opzionale che specifica il report in cui verranno memorizzati i risultati per revisione manuale, analisi e reporting. Il sistema aggiunge automaticamente un timestamp con il mese corrente. Se omesso o impostato su `null`, il sistema raggrupperà automaticamente i risultati per mese a scopo di reporting.	null	facoltativo

{
   "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"
   ]
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`accepted`	array	Un elenco di oggetti contenenti identificatori univoci e MSISDN che sono stati accettati per l'elaborazione.	false
`accepted_count`	integer	Il numero totale di MSISDN accettati con successo per l'elaborazione.	false
`rejected`	array	Un elenco di oggetti contenenti identificatori univoci e MSISDN che sono stati rifiutati per l'elaborazione, tipicamente a causa di numeri non validi. Nessun addebito viene applicato per le voci rifiutate.	false
`rejected_count`	integer	Il numero totale di MSISDN rifiutati a causa di errori di validazione.	false
`total_count`	integer	Il conteggio totale di MSISDN accettati e rifiutati che sono stati inviati per l'elaborazione.	false
`cost`	string	Un valore decimale rappresentato come stringa, che indica il costo totale in EUR per i lookup accettati.	false
`storage`	string	Il nome dello storage dove vengono aggiunti i risultati dei lookup, utilizzato per il reporting e i download CSV tramite l'interfaccia web.	false
`route`	string(3)	Un identificativo di tre caratteri che specifica il percorso utilizzato per questa richiesta di interrogazione.	false
`webhook_urls`	array	Gli URL webhook configurati nelle tue impostazioni API. I risultati vengono inviati qui.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Elaborazione Webhook

Una volta inviati, la nostra piattaforma inizia a elaborare i numeri di telefono forniti e invia i risultati all'URL webhook precedentemente specificato sul vostro server. I risultati vengono trasmessi come richiesta HTTP POST con un oggetto JSON nel corpo della richiesta.

Autenticazione

Autenticare il webhook ispezionando l'intestazione HTTP X-Signatures.

L'intestazione X-Signatures contiene un elenco di firme separate da punto e virgola. Ogni firma nell'elenco viene generata utilizzando uno dei secret API configurati nel vostro account. Per verificare il webhook, generare un hash SHA-256 utilizzando la chiave API, il secret e il corpo HTTP grezzo, quindi confrontarlo con le firme nell'elenco.

Una corrispondenza conferma che la richiesta è autentica e firmata con un secret sotto il vostro controllo.

Esempio di Codice

$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;
    }
}

La richiesta è valida se una qualsiasi delle firme fornite nell'intestazione corrisponde a un hash SHA256 calcolato sulla stringa concatenata della chiave API, del secret e del corpo HTTP.

Conferma di Ricezione

Il vostro server deve rispondere con un codice di stato HTTP 200 OK per confermare la ricezione avvenuta con successo. Se viene restituito un altro codice di risposta, si verifica un timeout (10 secondi) o si presenta qualsiasi altro problema di consegna, il sistema ritenterà automaticamente l'invio del webhook dopo un minuto. Se la richiesta continua a fallire, i tentativi seguiranno una strategia di backoff esponenziale, con successivi tentativi dopo 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuti.

Questo meccanismo di retry garantisce la massima affidabilità nella consegna dei risultati di lookup alla vostra infrastruttura. Riduce al minimo il rischio di perdita di dati dovuta a problemi di rete temporanei o interruzioni del server.

Payload Webhook

{
    "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
        }
    ]
}

Attributi del Payload Webhook

L'oggetto JSON contiene un attributo type => MNP insieme a un attributo results che include un elenco di oggetti lookup, come documentato di seguito.

Nome	Tipo	Descrizione	Nullable
`id`	string(12)	Un identificativo univoco di 12 caratteri per questa interrogazione.	false
`msisdn`	string	Il numero di telefono mobile valutato in questa richiesta di interrogazione.	false
`query_status`	string	Indica se il recupero delle informazioni di portabilità e di rete è avvenuto con successo. I valori possibili sono `OK` o `FAILED`.	false
`mccmnc`	string(5\|6)	Un codice MCCMNC di cinque o sei caratteri (tupla di mobile country code e mobile network code) che identifica la rete a cui appartiene attualmente il numero di telefono mobile.	true
`mcc`	string(3)	Un MCC di tre caratteri (mobile country code) che rappresenta il paese associato alla rete attuale del numero di telefono mobile.	true
`mnc`	string(2\|3)	Un MNC di due o tre caratteri (mobile network code) che identifica l'operatore di rete attuale per il numero di telefono mobile.	true
`is_ported`	boolean	Indica se il numero di telefono è stato portato dalla rete originale a un nuovo operatore.	true
`original_network_name`	string	Una stringa arbitraria (in inglese) che specifica il nome dell'operatore di rete originale del numero di telefono mobile ispezionato.	true
`original_country_name`	string	Una stringa arbitraria (in inglese) che indica il paese originale del numero di telefono mobile ispezionato.	true
`original_country_code`	string(2)	Un codice paese ISO di due caratteri che rappresenta il paese originale del numero di telefono mobile ispezionato.	true
`original_country_prefix`	string	Il prefisso internazionale del paese originale associato al numero di telefono mobile ispezionato.	true
`ported_network_name`	string	Specifica l'operatore di rete a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`ported_country_name`	string	Specifica il paese a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`ported_country_code`	string(2)	Un codice paese ISO di due caratteri che rappresenta il paese a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`ported_country_prefix`	string	Il prefisso internazionale del paese a cui è stato portato il numero di telefono mobile ispezionato, se applicabile.	true
`extra`	string	Una stringa arbitraria che fornisce dettagli aggiuntivi opzionali sul numero di telefono.	true
`cost`	string	Un valore decimale, rappresentato come stringa, che indica il costo in EUR per questa interrogazione.	true
`timestamp`	string	Un timestamp in formato W3C, comprensivo di informazioni sul fuso orario, che indica quando l'interrogazione è stata completata.	true
`storage`	string	Il nome di archiviazione (o nome del report) a cui sono stati aggiunti i risultati dell'interrogazione. Viene utilizzato per i download CSV e i report tramite l'interfaccia web.	true
`route`	string(3)	Un identificativo di tre caratteri che specifica il percorso utilizzato per questa richiesta di interrogazione.	true
`error_code`	integer	Un codice di errore interno opzionale che fornisce contesto aggiuntivo per la diagnostica dell'assistenza clienti.	true

Scorri Su

POST/nt-lookupprotetto

Esegue una ricerca sincrona del tipo di numero (NT). Questo endpoint è ideale se il tuo obiettivo principale è determinare in tempo reale se i numeri di telefono forniti appartengono a intervalli di numerazione di rete fissa, mobile, a tariffa maggiorata, VoIP, cercapersone o altri.

Le query NT rilevano in modo affidabile il tipo di numero di telefono; tuttavia, non indicano se il numero di destinazione è attualmente connesso a una rete e raggiungibile. Per ottenere informazioni sulla connettività in tempo reale, utilizza l'endpoint POST /hlr-lookup.

Se il tuo caso d'uso richiede informazioni precise su rete e portabilità (MCCMNC) ma non lo stato di connettività in tempo reale, utilizza l'endpoint POST /mnp-lookup per le query di portabilità del numero mobile.

Richiesta Risposta di Successo Risposta di Errore Riferimento Tipo

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

Payload

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`number`	string	Un numero di telefono in formato internazionale (ad es. +4989702626 o 004989702626).	null	mandatory
`route`	string(3)	Un identificatore facoltativo di tre caratteri che specifica il percorso per questa ricerca. Imposta su `null` o ometti questo parametro per applicare la tua mappa di routing personalizzata o lasciare che il nostro sistema determini automaticamente i percorsi migliori per questa richiesta.	null	facoltativo
`storage`	string	Un identificatore di archiviazione opzionale che specifica il report in cui verranno memorizzati i risultati per revisione manuale, analisi e reporting. Il sistema aggiunge automaticamente un timestamp con il mese corrente. Se omesso o impostato su `null`, il sistema raggrupperà automaticamente i risultati per mese a scopo di reporting.	null	facoltativo

{
     "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"
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`id`	string(12)	Un identificatore univoco assegnato a questa richiesta di lookup.	false
`number`	string	Il numero di telefono che è stato valutato durante questa richiesta di lookup.	false
`number_type`	string	Il tipo di numero rilevato. I valori possibili includono: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indica se le informazioni sul tipo di numero sono state ottenute con successo. Restituisce `OK` in caso di successo, o `FAILED` se il lookup è fallito.	false
`is_valid`	boolean	Indica se il numero di telefono è sintatticamente valido.	true
`invalid_reason`	string	Un messaggio di testo in inglese che specifica perché il numero di telefono è considerato non valido (ad es. "too short" o "invalid prefix"), oppure `null` se il numero è valido.	true
`is_possibly_ported`	boolean	Indica se il numero di telefono potrebbe essere stato portato dall'operatore originale a un operatore diverso. Per informazioni definitive sulla portabilità, utilizzare i lookup MNP.	true
`is_vanity_number`	boolean	Indica se il numero di telefono è un numero vanity, ovvero include caratteri alfabetici.	true
`qualifies_for_hlr_lookup`	boolean	Indica se il numero di telefono è idoneo per query aggiuntive tramite lookup HLR.	true
`mccmnc`	string(5\|6)	Una stringa di cinque o sei caratteri che rappresenta la tupla MCCMNC (codice paese mobile e codice rete mobile) che identifica la rete originale del numero di telefono mobile.	true
`mcc`	string(3)	Una stringa di tre caratteri che rappresenta il MCC (codice paese mobile) che identifica il paese associato alla rete mobile originale del numero di telefono.	true
`mnc`	string(2\|3)	Una stringa di due o tre caratteri che rappresenta il MNC (codice rete mobile) che identifica l'operatore di rete mobile originale del numero di telefono.	true
`original_network_name`	string	Una stringa di testo arbitraria in inglese che specifica il nome dell'operatore di rete originale del numero di telefono mobile ispezionato.	true
`original_country_name`	string	Una stringa di testo arbitraria in inglese che specifica il paese originale associato al numero di telefono mobile ispezionato.	true
`original_country_code`	string(2)	Un codice paese ISO di due caratteri che indica il paese originale del numero di telefono mobile ispezionato.	true
`regions`	array	Un elenco di stringhe leggibili in inglese che specificano la/e regione/i geografica/che associata/e a questo numero di telefono.	true
`timezones`	array	Un elenco di fusi orari (in formato Olson) associati a questo numero di telefono.	true
`info_text`	string	Una stringa arbitraria che può contenere informazioni aggiuntive sul numero di telefono.	true
`cost`	string	Un valore decimale rappresentato come stringa, che indica il costo (in EUR) di questo lookup.	true
`timestamp`	string	Un timestamp in formato W3C (incluso il fuso orario) che indica quando il lookup è stato completato.	true
`storage`	string	Specifica il nome dello storage in cui sono stati salvati i risultati del lookup. Corrisponde al nome del report utilizzato per i download CSV e le analisi tramite l'interfaccia web.	true
`route`	string(3)	Un identificativo di tre caratteri che specifica il percorso utilizzato per questa richiesta di interrogazione.	true

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Tipo	Descrizione
LANDLINE	Numero di telefono fisso.
MOBILE	Numero di telefono mobile. Idoneo per interrogazioni HLR per ottenere informazioni aggiuntive sullo stato di connessione, rete, portabilità e roaming.
MOBILE_OR_LANDLINE	Numero di telefono fisso o mobile. Potrebbe essere idoneo per interrogazione HLR.
TOLL_FREE	Numero verde.
PREMIUM_RATE	Numero a tariffazione maggiorata con costi aggiuntivi.
SHARED_COST	Numero a costo condiviso. Generalmente meno costoso dei numeri a tariffazione maggiorata.
VOIP	Numero di telefono Voice over IP. Include numeri TSoIP (Telephony Service over IP).
PAGER	Numero cercapersone. Generalmente senza funzionalità vocale.
UAN	Numero di Accesso Universale (Numero Aziendale). Può essere instradato verso uffici specifici ma consente di utilizzare un unico numero per l'azienda.
VOICEMAIL	Numero di segreteria telefonica.
UNKNOWN	Impossibile determinare il tipo di numero.

Scorri Su

POST/nt-lookups protetto

Questo endpoint avvia una serie di ricerche asincrone del tipo di numero con risultati inviati al tuo server tramite webhook. È adatto se il tuo obiettivo principale è determinare se i numeri di telefono forniti appartengono a intervalli di numerazione di rete fissa, mobile, tariffazione premium, VoIP, cercapersone o altro. Ottimizzato per l'elaborazione rapida di grandi volumi di numeri, questo endpoint è ideale per operazioni massive (es. pulizia database). Per il traffico in tempo reale e casi d'uso critici, utilizzare invece l'endpoint POST /nt-lookup.

È necessario specificare un URL webhook nelle impostazioni API come prerequisito per invocare questo endpoint.

Richiesta Risposta di Successo Risposta di Errore Webhook Riferimento Tipo

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

Payload

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`numbers`	array	Un array di numeri di telefono in formato internazionale (es. +14156226819 o 004989702626). È possibile includere un massimo di 1000 numeri per richiesta.	null	obbligatorio
`route`	string(3)	Un identificatore opzionale di tre caratteri che specifica il percorso per questa ricerca. Impostare su `null` o omettere questo parametro per applicare la mappa di routing personalizzata o lasciare che il sistema determini automaticamente il percorso migliore per questa richiesta.	null	facoltativo
`storage`	string	Un identificatore di archiviazione opzionale che specifica il report in cui verranno memorizzati i risultati per revisione manuale, analisi e reporting. Il sistema aggiunge automaticamente un timestamp con il mese corrente. Se omesso o impostato su `null`, il sistema raggrupperà automaticamente i risultati per mese a scopo di reporting.	null	facoltativo

{
   "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"
   ]
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`accepted`	array	Un array di oggetti, ciascuno contenente un identificatore univoco e un numero di telefono accettato per l'elaborazione.	false
`accepted_count`	integer	Il conteggio totale dei numeri di telefono accettati per l'elaborazione.	false
`rejected`	array	Un array di oggetti, ciascuno contenente un identificatore univoco e un numero di telefono rifiutato per l'elaborazione. Generalmente, questi numeri non sono validi e non viene applicato alcun addebito.	false
`rejected_count`	integer	Il conteggio totale dei numeri di telefono rifiutati per l'elaborazione.	false
`total_count`	integer	Il conteggio totale dei numeri di telefono accettati e rifiutati inviati per l'elaborazione.	false
`cost`	string	Una stringa che rappresenta un valore decimale che indica il costo in EUR per queste ricerche.	false
`storage`	string	Il nome dell'archivio (report) in cui sono stati aggiunti i risultati delle ricerche. Questo nome viene utilizzato per i download CSV e le analisi tramite l'interfaccia web.	false
`route`	string(3)	Un identificatore di tre caratteri che specifica il percorso utilizzato per questa richiesta di ricerca.	false
`webhook_urls`	array	Gli URL webhook configurati nelle tue impostazioni API. I risultati vengono inviati qui.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Elaborazione Webhook

Una volta inviati, la nostra piattaforma inizia a elaborare i numeri di telefono forniti e invia i risultati all'URL webhook precedentemente specificato sul vostro server. I risultati vengono trasmessi come richiesta HTTP POST con un oggetto JSON nel corpo della richiesta.

Autenticazione

Autenticare il webhook ispezionando l'intestazione HTTP X-Signatures.

L'intestazione X-Signatures contiene un elenco di firme separate da punto e virgola. Ogni firma nell'elenco viene generata utilizzando uno dei secret API configurati nel vostro account. Per verificare il webhook, generare un hash SHA-256 utilizzando la chiave API, il secret e il corpo HTTP grezzo, quindi confrontarlo con le firme nell'elenco.

Una corrispondenza conferma che la richiesta è autentica e firmata con un secret sotto il vostro controllo.

Esempio di Codice

$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;
    }
}

La richiesta è valida se una qualsiasi delle firme fornite nell'intestazione corrisponde a un hash SHA256 calcolato sulla stringa concatenata della chiave API, del secret e del corpo HTTP.

Conferma di Ricezione

Il vostro server deve rispondere con un codice di stato HTTP 200 OK per confermare la ricezione avvenuta con successo. Se viene restituito un altro codice di risposta, si verifica un timeout (10 secondi) o si presenta qualsiasi altro problema di consegna, il sistema ritenterà automaticamente l'invio del webhook dopo un minuto. Se la richiesta continua a fallire, i tentativi seguiranno una strategia di backoff esponenziale, con successivi tentativi dopo 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minuti.

Questo meccanismo di retry garantisce la massima affidabilità nella consegna dei risultati di lookup alla vostra infrastruttura. Riduce al minimo il rischio di perdita di dati dovuta a problemi di rete temporanei o interruzioni del server.

Payload Webhook

{
   "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"
      }
   ]
}

Attributi del Payload Webhook

L'oggetto JSON contiene un attributo type => NT insieme a un attributo results che include un elenco di oggetti lookup, come documentato di seguito.

Nome	Tipo	Descrizione	Nullable
`id`	string(12)	Un identificatore univoco assegnato a questa richiesta di lookup.	false
`number`	string	Il numero di telefono che è stato valutato durante questa richiesta di lookup.	false
`number_type`	string	Il tipo di numero rilevato. I valori possibili includono: `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indica se le informazioni sul tipo di numero sono state ottenute con successo. Restituisce `OK` in caso di successo, o `FAILED` se il lookup è fallito.	false
`is_valid`	boolean	Indica se il numero di telefono è sintatticamente valido.	true
`invalid_reason`	string	Un messaggio di testo in inglese che specifica perché il numero di telefono è considerato non valido (ad es. "too short" o "invalid prefix"), oppure `null` se il numero è valido.	true
`is_possibly_ported`	boolean	Indica se il numero di telefono potrebbe essere stato portato dall'operatore originale a un operatore diverso. Per informazioni definitive sulla portabilità, utilizzare i lookup MNP.	true
`is_vanity_number`	boolean	Indica se il numero di telefono è un numero vanity, ovvero include caratteri alfabetici.	true
`qualifies_for_hlr_lookup`	boolean	Indica se il numero di telefono è idoneo per query aggiuntive tramite lookup HLR.	true
`mccmnc`	string(5\|6)	Una stringa di cinque o sei caratteri che rappresenta la tupla MCCMNC (codice paese mobile e codice rete mobile) che identifica la rete originale del numero di telefono mobile.	true
`mcc`	string(3)	Una stringa di tre caratteri che rappresenta il MCC (codice paese mobile) che identifica il paese associato alla rete mobile originale del numero di telefono.	true
`mnc`	string(2\|3)	Una stringa di due o tre caratteri che rappresenta il MNC (codice rete mobile) che identifica l'operatore di rete mobile originale del numero di telefono.	true
`original_network_name`	string	Una stringa di testo arbitraria in inglese che specifica il nome dell'operatore di rete originale del numero di telefono mobile ispezionato.	true
`original_country_name`	string	Una stringa di testo arbitraria in inglese che specifica il paese originale associato al numero di telefono mobile ispezionato.	true
`original_country_code`	string(2)	Un codice paese ISO di due caratteri che indica il paese originale del numero di telefono mobile ispezionato.	true
`regions`	array	Un elenco di stringhe leggibili in inglese che specificano la/e regione/i geografica/che associata/e a questo numero di telefono.	true
`timezones`	array	Un elenco di fusi orari (in formato Olson) associati a questo numero di telefono.	true
`info_text`	string	Una stringa arbitraria che può contenere informazioni aggiuntive sul numero di telefono.	true
`cost`	string	Un valore decimale rappresentato come stringa, che indica il costo (in EUR) di questo lookup.	true
`timestamp`	string	Un timestamp in formato W3C (incluso il fuso orario) che indica quando il lookup è stato completato.	true
`storage`	string	Specifica il nome dello storage in cui sono stati salvati i risultati del lookup. Corrisponde al nome del report utilizzato per i download CSV e le analisi tramite l'interfaccia web.	true
`route`	string(3)	Un identificativo di tre caratteri che specifica il percorso utilizzato per questa richiesta di interrogazione.	true

Tipo	Descrizione
LANDLINE	Numero di telefono fisso.
MOBILE	Numero di telefono mobile. Idoneo per interrogazioni HLR per ottenere informazioni aggiuntive sullo stato di connessione, rete, portabilità e roaming.
MOBILE_OR_LANDLINE	Numero di telefono fisso o mobile. Potrebbe essere idoneo per interrogazione HLR.
TOLL_FREE	Numero verde.
PREMIUM_RATE	Numero a tariffazione maggiorata con costi aggiuntivi.
SHARED_COST	Numero a costo condiviso. Generalmente meno costoso dei numeri a tariffazione maggiorata.
VOIP	Numero di telefono Voice over IP. Include numeri TSoIP (Telephony Service over IP).
PAGER	Numero cercapersone. Generalmente senza funzionalità vocale.
UAN	Numero di Accesso Universale (Numero Aziendale). Può essere instradato verso uffici specifici ma consente di utilizzare un unico numero per l'azienda.
VOICEMAIL	Numero di segreteria telefonica.
UNKNOWN	Impossibile determinare il tipo di numero.

Scorri Su

GET/routeprotetto

Recupera il percorso che verrà selezionato automaticamente quando si esegue una ricerca HLR senza specificare il parametro route.

La selezione automatica del percorso si basa sulla mappa di routing recuperabile tramite l'endpoint GET /hlr-coverage, che deriva principalmente da GET /routing-map. È possibile personalizzare la propria mappa di routing e definire regole personalizzate nelle impostazioni dell'account.

Richiesta Risposta di Successo Risposta di Errore

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`msisdn`	string	Il MSISDN per il quale recuperare le informazioni di routing selezionate automaticamente.	null	obbligatorio

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

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`route`	string	Il percorso consigliato.	false
`confidence_level`	string	Il livello di confidenza con cui questa rotta è stata selezionata, ovvero `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	L'MCCMNC basato sul piano di numerazione per questo numero.	false
`origin`	string	L'origine su cui si basa la decisione di routing, ovvero `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."
    ]
}

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/routesprotetto

Questo endpoint restituisce un elenco delle route HLR, MNP e NT disponibili. Ogni route, con le relative funzionalità e limitazioni, è illustrata nella pagina dettagli routing.

Richiesta Risposta di Successo Risposta di Errore

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

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

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`routes`	object	Un oggetto con le route raggruppate per tipo di route.	false
`HLR\|MNP\|NT`	string[]	Contiene un elenco di identificatori di route.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/routing-mapprotetto

Recupera la configurazione di routing automatico attualmente applicata alle ricerche HLR per il tuo account. Questa configurazione predefinita viene utilizzata ogni volta che invii ricerche HLR senza specificare un parametro route. Puoi personalizzare la tua mappa di routing e creare regole personalizzate nelle impostazioni dell'account.

La gerarchia di configurazione si estende dalle regole a livello di paese alle regole a livello di MCCMNC, fino alle mappature dei singoli prefissi telefonici. In pratica, ciò significa che le mappature dei singoli prefissi telefonici hanno la precedenza sulle assegnazioni MCCMNC in conflitto, che a loro volta prevalgono sulle regole a livello di paese. Si prega di notare che il fallback MNP ha la precedenza su eventuali regole personalizzate in conflitto quando è abilitato.

Richiesta Risposta di Successo Risposta di Errore

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"
            }
         ]
      }
   }
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`default_route`	string	Il percorso predefinito utilizzato quando non è possibile determinare un'opzione di routing preferita per un MSISDN e non si applicano regole di routing personalizzate.	false
`mnp_fallback`	boolean	Indica se il fallback MNP è abilitato. Quando abilitato e le query HLR non sono supportate da una rete (stato di connettività non disponibile), il sistema eseguirà invece una ricerca MNP.	false
`mccmncs`	array	Una mappatura dei codici MCCMNC ai loro percorsi selezionati automaticamente. Quando si esegue una ricerca HLR per un numero in un determinato MCCMNC, viene utilizzato il percorso corrispondente.	false
`mccmnc`	string(5\|6)	Un MCCMNC (combinazione di codice paese mobile e codice rete mobile) di cinque o sei caratteri che identifica l'operatore di rete mobile.	false
`countrycode`	string(2)	Un codice paese ISO di due caratteri, che identifica il paese della rete.	false
`route`	string(3)	Il percorso selezionato per la rete.	false
`mno`	string	Il marchio commerciale con cui questa rete opera verso i consumatori.	false
`confidence`	string	Il livello di affidabilità con cui è stata effettuata la selezione. I valori possibili sono: HIGH, NORMAL, LOW, MNP_REDIRECT. In quest'ultimo caso, il sistema reindirizza il traffico verso questa rete a MNP, se questo comportamento è abilitato nel tuo account. Altrimenti utilizza il percorso predefinito nell'account.	false
`origin`	string	L'origine su cui si basa la selezione. I valori possibili sono: `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	Un elenco di regole di routing personalizzate basate su prefisso configurate nel tuo account, se presenti.	false
`countrycode`	string(2)	Un codice paese ISO di due caratteri, che identifica il paese del prefisso.	false
`cns`	string	Il prefisso a cui si applica la regola di routing.	false
`route`	string(3)	Il percorso selezionato per il prefisso.	false
`mccmnc`	string(5\|6)	Un MCCMNC (combinazione di codice paese mobile e codice rete mobile) di cinque o sei caratteri che identifica l'operatore di rete mobile.	true
`mno`	string	Il marchio commerciale con cui questa rete opera verso i consumatori.	true
`countries`	array	Un elenco di regole personalizzate basate su paese configurate nel tuo account, se presenti.	false
`countrycode`	string(2)	Un codice paese ISO di due caratteri, che identifica il paese.	false
`route`	string(3)	Il percorso selezionato per il paese.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/hlr-coverage protetto

Restituisce informazioni sulla copertura HLR per supportare decisioni basate sui dati. Questo endpoint ti aiuta ad analizzare le opzioni di routing HLR in tempo reale attraverso le reti mobili, identificare i percorsi più efficaci per le tue regioni target e configurare il routing automatico.

Le rotte consigliate da GET /route si basano sui dati di copertura recuperati qui. I dati di copertura sono disponibili anche nella pagina copertura di rete. Puoi personalizzare ulteriormente la tua mappa di routing e definire regole nelle impostazioni account.

Ti consigliamo di familiarizzare con questa guida per interpretare correttamente i risultati.

Richiesta Risposta di Successo Risposta di Errore Riferimento Stati

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`countrycode`	string(2)	Un codice paese ISO a due lettere obbligatorio utilizzato per filtrare i risultati, restituendo solo i record associati al paese specificato.	null	obbligatorio
`sample_size`	string	Un parametro facoltativo che specifica la dimensione del campione. I valori possibili sono `LARGE`, `MEDIUM`, `SMALL`. Campioni più grandi coprono un periodo di tempo più lungo, campioni più piccoli coprono un periodo molto recente.	LARGE	facoltativo

{
   "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
            }
         ]
      }
   ]
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`name`	string	Il nome del paese selezionato in testo inglese.	false
`countrycode`	string(2)	Il codice paese ISO a due caratteri del paese selezionato.	false
`prefix`	string	Il prefisso internazionale del paese selezionato.	false
`mccs`	string[]	Un elenco di MCC (mobile country code) associati al paese selezionato.	false
`carriers`	object[]	Un elenco di oggetti operatore con metriche di connettività specifiche per rotta.	false
`mno`	string	Il nome dell'operatore di rete mobile in testo inglese.	false
`mccmnc`	string	L'MCCMNC dell'operatore di rete mobile.	false
`mcc`	string	Il MCC (mobile country code) dell'operatore di rete mobile.	false
`mnc`	string	Il MNC (mobile network code) dell'operatore di rete mobile.	false
`routes`	object[]	Un elenco di risultati di connettività specifici per rotta.	false
`route`	string	La rotta a cui si applicano le informazioni di connettività.	false
`selected`	bool	Indica se questa è la rotta selezionata per il routing automatico.	false
`selection_confidence`	string	Il livello di confidenza con cui questa rotta è stata selezionata, ovvero `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Contiene null se questa non è la rotta selezionata.	true
`n`	int	Il numero totale di lookup in questo campione.	false
`CONNECTED`	int	Il numero di lookup HLR che hanno restituito uno stato CONNECTED.	false
`CONNECTED_PCT`	float	La percentuale di lookup HLR che hanno restituito uno stato CONNECTED.	false
`ABSENT`	int	Il numero di lookup HLR che hanno restituito uno stato ABSENT.	false
`ABSENT_PCT`	float	La percentuale di lookup HLR che hanno restituito uno stato ABSENT.	false
`INVALID_MSISDN`	int	Il numero di lookup HLR che hanno restituito uno stato INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	La percentuale di lookup HLR che hanno restituito uno stato INVALID_MSISDN.	false
`UNDETERMINED`	int	Il numero di lookup HLR che hanno restituito uno stato UNDETERMINED.	false
`UNDETERMINED_PCT`	float	La percentuale di lookup HLR che hanno restituito uno stato UNDETERMINED.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Stato	Descrizione
CONNECTED	Il numero è valido e il dispositivo di destinazione è attualmente connesso alla rete mobile. Chiamate, SMS e altri servizi dovrebbero raggiungere il destinatario con successo.
ABSENT	Il numero è valido, ma il dispositivo di destinazione è spento o temporaneamente fuori dalla copertura di rete. Messaggi o chiamate potrebbero non essere recapitati fino a quando il dispositivo non si riconnette alla rete.
INVALID_MSISDN	Il numero non è valido o non è attualmente assegnato ad alcun abbonato sulla rete mobile. Chiamate e messaggi a questo numero non andranno a buon fine.
UNDETERMINED	Non è stato possibile determinare lo stato di connettività del numero. Ciò potrebbe essere dovuto a un numero non valido, a una risposta di errore SS7 o a una mancanza di connettività con l'operatore di rete di destinazione. Verificare il codice di errore e il relativo campo descrittivo per ulteriori informazioni diagnostiche.

Scorri Su

GET/mnp-coverageprotetto

Questo endpoint restituisce un elenco di operatori di rete mobile, insieme ai relativi identificatori MCCMNC, attualmente supportati per le ricerche di portabilità del numero mobile.

Richiesta Risposta di Successo Risposta di Errore

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`countrycode`	string(2)	Un codice paese ISO a due lettere opzionale utilizzato per filtrare i risultati MCCMNC, restituendo solo i dati relativi al paese specificato.	null	facoltativo

{
   "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"
      }
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`items[]`	array	Un elenco di operatori di rete mobile.	false
`country_name`	string	Il nome del paese in inglese.	false
`country_code`	string(2)	Un codice paese ISO a due lettere.	false
`mccmnc`	string(5\|6)	Un MCCMNC (combinazione di codice paese mobile e codice rete mobile) di cinque o sei caratteri che identifica l'operatore di rete mobile.	false
`mcc`	string(3)	Un MCC (codice paese mobile) di tre caratteri che rappresenta il paese della rete.	false
`mnc`	string(2\|3)	Un MNC (codice rete mobile) di due o tre caratteri che rappresenta lo specifico operatore di rete mobile.	false
`brand`	string	Il marchio commerciale con cui questa rete opera verso i consumatori.	true
`operator`	string	La ragione sociale dell'operatore di rete mobile.	true

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/price-listprotetto

Questo endpoint restituisce un elenco di paesi in cui sono supportate solo le ricerche MNP e le query HLR non sono disponibili per queste destinazioni.

Richiesta Risposta di Successo Risposta di Errore

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

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

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`countries`	string[]	Un elenco di codici paese ISO a due caratteri.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/mccmncsprotetto

Questo endpoint restituisce un elenco completo degli operatori di rete mobile insieme ai relativi identificatori MCCMNC e informazioni contestuali aggiuntive.

Richiesta Risposta di Successo Risposta di Errore

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`countrycode`	string(2)	Un codice paese ISO a due lettere opzionale utilizzato per filtrare i risultati MCCMNC, restituendo solo i record associati al paese specificato.	null	facoltativo

{
   "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"
      }
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`items`	object[]	Un elenco di operatori di rete mobile.	false
`country_name`	string	Il nome completo del paese in inglese.	false
`country_code`	string(2)	Un codice paese ISO a due lettere che rappresenta il paese dell'operatore mobile.	false
`mccmnc`	string(5\|6)	Una stringa di cinque o sei caratteri che rappresenta l'MCCMNC, che identifica in modo univoco l'operatore di rete mobile.	false
`mcc`	string(3)	Un Mobile Country Code (MCC) di tre caratteri che identifica il paese in cui opera la rete mobile.	false
`mnc`	string(2\|3)	Un Mobile Network Code (MNC) di due o tre caratteri che specifica la rete mobile all'interno dell'MCC indicato.	false
`brand`	string	Il nome commerciale con cui la rete opera ed è riconosciuta dai consumatori.	true
`operator`	string	Il nome ufficiale dell'operatore di rete mobile, tipicamente l'entità legale che gestisce la rete.	true
`parent_mccmnc`	string(5\|6)	Una stringa di cinque o sei caratteri che rappresenta l'MCCMNC dell'operatore di rete mobile principale, se presente.	true

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/priceprotetto

Questo endpoint restituisce il prezzo per una ricerca HLR, MNP o NT.

Richiesta Risposta di Successo Risposta di Errore

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

Parametri Richiesta

Chiave	Tipo	Descrizione	Predefinito	Obbligatorio
`msisdn`	string	Il numero di telefono per cui recuperare il prezzo. In formato internazionale.	null	obbligatorio
`route_type`	string	Il tipo di route, ad es. `HLR`, `MNP`, `NT`.	null	obbligatorio
`route`	string(3)	La route per cui deve essere calcolato il prezzo. Per impostazione predefinita, viene utilizzata la route determinata dal routing automatico.	null	facoltativo

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

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`price`	object	Un oggetto con i dettagli del prezzo.	false
`amount`	string	L'importo in EUR.	false
`msisdn`	string	Il numero MSISDN a cui si applica questo prezzo.	false
`route_type`	string(2\|3)	Il tipo di route a cui si applica questo prezzo.	false
`route`	string(3)	La route a cui si applica questo prezzo.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/price-listprotetto

Questo endpoint restituisce i prezzi configurati nel tuo account.

Richiesta Risposta di Successo Risposta di Errore

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"
      }
   ]
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`pricing`	object[]	Un elenco di oggetti contenenti informazioni sui prezzi.	false
`route`	string	Il percorso a cui si applica questo prezzo.	false
`countrycode`	string	Il codice paese ISO a due caratteri a cui si applica questo prezzo per il percorso corrispondente, se presente.	true
`countryname`	string	Il nome del paese in inglese corrispondente al codice paese, se presente.	true
`mccmnc`	string	Il codice MCCMNC a cui si applica questo prezzo per il percorso corrispondente, se presente. Sostituisce il prezzo a livello di paese.	true
`cns`	string	Il prefisso telefonico a cui si applica questo prezzo per il percorso corrispondente, se presente. Sostituisce il prezzo a livello di paese e a livello di MCCMNC.	true
`route_type`	string	Il tipo di percorso corrispondente, ad esempio `HLR`, `MNP`, `NT`.	false
`route_type`	string	Il prezzo corrispondente in EUR.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/balanceprotetto

Questo endpoint recupera il saldo corrente del tuo account, consentendoti di automatizzare i processi in base allo stato del tuo credito. Funziona perfettamente con le email di notifica credito basso che puoi configurare nella tua pagina pagamenti.

Richiesta Risposta di Successo Risposta di Errore

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

{
    "balance":"1002.90"
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`balance`	string	Il saldo corrente del tuo account in EUR. Un valore decimale di tipo stringa.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/pingpubblico

Questo endpoint invia una richiesta ping all'API, fornendo un metodo semplice per testare la connessione all'API HLR Lookups.

Richiesta Risposta di Successo Risposta di Errore

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

{
    "success":true
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`success`	boolean	Indica che la richiesta è stata elaborata con successo.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/timepubblico

Questo endpoint restituisce un timestamp Unix che rappresenta l'ora corrente del server HLR Lookups. Utilizzalo per sincronizzare l'orologio del tuo server durante la generazione della firma Digest-Auth per l'autenticazione, assicurando che eventuali discrepanze tra l'ora del tuo server e quella del server HLR Lookups vengano corrette.

Richiesta Risposta di Successo Risposta di Errore

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

{
    "time":1525898643
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`time`	integer	Timestamp Unix che rappresenta l'ora corrente del server HLR Lookups.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

GET/auth-testprotetto

Questo endpoint serve come test iniziale per la tua implementazione Basic-Auth o, preferibilmente, Digest-Auth.

Richiesta Basic Auth Richiesta Digest Auth Risposta di Successo Risposta di Errore

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

Header della Richiesta

Chiave	Tipo	Descrizione
`X-Basic`	string	Hash SHA256 di `YOUR_API_KEY:YOUR_API_SECRET`. Includere il simbolo dei due punti (:) nell'hash.

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"

Header della Richiesta

Chiave	Tipo	Descrizione
`X-Digest-Key`	string	La tua Chiave API HLR Lookups
`X-Digest-Signature`	string	Firma Digest-Auth univoca (vedi autenticazione)
`X-Digest-Timestamp`	integer	Timestamp Unix corrente (vedi anche `GET /time`)

{
    "success":true
}

Attributi della Risposta di Successo

Nome	Tipo	Descrizione	Nullable
`success`	boolean	Indica che la richiesta è stata elaborata con successo.	false

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

Parametri Risposta Errore

Nome	Tipo	Descrizione	Nullable
`errors[]`	string[]	Un elenco di stringhe che spiegano l'errore.	false

Scorri Su

Documentazione API Legacy

Si prega di notare che l'API legacy è deprecata ed è prevista la sua dismissione in futuro. Raccomandiamo vivamente di effettuare l'aggiornamento alla versione più recente il prima possibile.

Se hai implementato la nostra API HLR Lookups tra il 2013 e l'inizio del 2020, stai utilizzando la nostra API legacy. In tal caso, consulta la nostra documentazione API legacy.

Documentazione API Legacy

Documentazione API

Guida Introduttiva

Ricerche HLR

Ricerche MNP

Ricerche NT

Routing

Prezzi

Strumenti

Guida Introduttiva

Utilizzo dell'API HLR Lookups

Richiesta di Esempio

Payload di Esempio

Risposta di Successo application/json

Servizi di Ricerca Aggiuntivi

Ricerche di Portabilità del Numero Mobile (MNP)

Ricerche di Rilevamento del Tipo di Numero (NT)

Kit di Sviluppo Software (SDK)

Strumenti

Non Sei uno Sviluppatore?

Autenticazione

Chiave API e Secret API

HTTP Basic Auth

Consigliato: Header X-Basic con SHA256

Richiesta Basic Auth

Header di Autenticazione Basic

Esempio di Codice

Esempio di Richiesta

Header della Richiesta

Costruzione della Firma

Componenti della Firma Digest

Esempi di Codice

Concetti

API di interrogazione HLR sincrona

API HLR Lookup Asincrona

SDK (Software Development Kit)

SDK PHP

SDK NodeJS

SDK Ruby

POST/hlr-lookupprotetto

Payload

Parametri Richiesta

Attributi della Risposta di Successo

Parametri Risposta Errore

POST/hlr-lookupsprotetto

Payload

Parametri Richiesta

Attributi della Risposta di Successo

Parametri Risposta Errore

Elaborazione Webhook

Autenticazione

Esempio di Codice

Conferma di Ricezione

Payload Webhook

Attributi del Payload Webhook

POST/mnp-lookupprotetto

Payload

Parametri Richiesta

Attributi della Risposta di Successo

Parametri Risposta Errore

POST/mnp-lookupsprotetto

Payload

Parametri Richiesta

Attributi della Risposta di Successo

Parametri Risposta Errore

Elaborazione Webhook

Autenticazione

Esempio di Codice

Conferma di Ricezione

Payload Webhook

Attributi del Payload Webhook

POST/nt-lookupprotetto

Payload

Parametri Richiesta

Attributi della Risposta di Successo

Parametri Risposta Errore

POST/nt-lookups protetto

Payload

Parametri Richiesta

Attributi della Risposta di Successo

Parametri Risposta Errore