Premiers Pas

L'infrastructure mondiale des réseaux mobiles repose sur un système appelé réseau de signalisation SS7. Ce réseau facilite l'échange de données d'abonnés, le routage d'appels, la transmission de SMS et les mises à jour en temps réel du statut de connectivité mobile entre opérateurs. Chaque réseau mobile maintient un registre de localisation nominal (HLR) - une base de données centrale qui stocke les informations essentielles sur ses abonnés.

La technologie HLR Lookup permet aux entreprises d'interroger ces registres et de récupérer les détails de connectivité et de réseau en temps réel pour tout numéro de téléphone mobile. Cela inclut l'état d'activation du téléphone, le réseau auquel il est actuellement rattaché, s'il a été porté, si le numéro est valide ou désactivé, et s'il est en itinérance.

L'API HLR Lookups fournit un accès transparent et en temps réel à ces données, permettant aux entreprises de vérifier les numéros mobiles, d'optimiser le routage et d'améliorer les communications avec leurs clients. Cette documentation vous guidera dans l'intégration de HLR Lookups dans votre logiciel, permettant la récupération automatisée d'informations mobiles en temps réel.

Utilisation de l'API HLR Lookups

L'exécution de requêtes HLR Lookup est rapide, sécurisée et simple. Une fois inscrit et après avoir obtenu votre clé API, vous pouvez vous authentifier et lancer des recherches instantanées avec de simples requêtes HTTP POST, via POST /hlr-lookup. Vous pouvez également traiter de grands volumes de données en optant pour des requêtes API asynchrones rapides avec des résultats renvoyés à votre serveur via webhook, comme expliqué dans la section concepts.

Exemple de Requête

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'authentification est fournie via les en-têtes HTTP, et payload.json doit contenir (au minimum) l'objet JSON suivant :

Exemple de Charge Utile

{
   "msisdn": "+14156226819"
}

En cas de succès, vous recevrez une réponse contenant les détails de connectivité en temps réel pour le numéro mobile spécifié.

Réponse de succès 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"
}

Pour une description complète des attributs de requête et de réponse ainsi que des statuts de connectivité, consultez POST /hlr-lookup.

Services de Recherche Supplémentaires

Recherches de Portabilité des Numéros Mobiles (MNP)

Utilisez les recherches MNP pour déterminer la propriété du réseau et les détails de portabilité sans interroger la connectivité en temps réel. Si vous avez uniquement besoin du MCCMNC d'un numéro, consultez POST /mnp-lookup.

Recherches de Détection de Type de Numéro (NT)

Déterminez si un numéro de téléphone appartient à une ligne fixe, un mobile, un numéro surtaxé, VoIP, pager ou d'autres plages de plan de numérotation avec POST /nt-lookup.

Kits de Développement Logiciel (SDK)

L'API HLR Lookups fonctionne avec tout client REST dans n'importe quel langage de programmation et nous avons publié des SDK pour PHP, Ruby et NodeJS sur notre GitHub pour vous aider à démarrer rapidement.

Outils

Pour garantir une expérience de développement optimale, nous proposons une suite complète d'outils, incluant la surveillance des requêtes API et webhooks dans le navigateur, la liste blanche d'adresses IP, des options d'authentification robustes et un point de terminaison de test d'authentification.

Vous n'êtes pas Développeur ?

Les recherches HLR et les requêtes de portabilité des numéros peuvent être effectuées sans aucune programmation. Découvrez notre client web entreprise et nos fonctionnalités de reporting basées sur navigateur.

Authentification

Pour garantir la sécurité et un contrôle d'accès approprié, la plupart des requêtes vers l'API HLR Lookups nécessitent une authentification. Les endpoints sont classés comme publics ou protégés. Lors de l'accès à un endpoint protégé, votre requête doit être authentifiée en utilisant votre clé API et votre secret via la méthode Digest-Auth ou Basic-Auth. Digest-Auth est l'option la plus sécurisée et est fortement recommandée. Utilisez l'endpoint GET /auth-test pour vérifier votre configuration d'authentification.

Clé API et Secret API

Obtenez votre clé API et votre secret depuis la page Paramètres API. Vous pouvez également configurer votre méthode d'authentification préférée et activer la liste blanche d'adresses IP pour une sécurité renforcée. Si vous soupçonnez que votre secret API a été compromis, vous pouvez en générer un nouveau à tout moment.

Basic Auth Digest Auth Liste blanche IP

L'authentification Basic standard est facile à implémenter et largement supportée. Vous pouvez vous authentifier en transmettant votre clé API et votre secret comme paire user:pass dans la requête HTTP.

HTTP Basic Auth

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

Cela envoie un en-tête Authorization :

Authorization: Basic BASE64(YOUR_API_KEY:YOUR_API_SECRET)

Recommandé : En-tête X-Basic avec SHA256

Pour une sécurité améliorée, vous pouvez envoyer un hash SHA256 de vos identifiants au lieu de les transmettre directement en base64. Pour utiliser cette méthode, calculez le hash de votre paire YOUR_API_KEY:YOUR_API_SECRET et envoyez-le via l'en-tête X-Basic :

Requête Basic Auth

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

En-têtes d'authentification Basic

Clé	Type	Description
`X-Basic`	string	Hash SHA256 de `YOUR_API_KEY:YOUR_API_SECRET`. Incluez le symbole deux-points (:) dans le hash.	obligatoire

Exemple de code

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

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

Digest-Auth est la méthode recommandée pour sécuriser l'accès aux endpoints protégés de l'API HLR Lookup. Chaque requête doit inclure les en-têtes suivants : X-Digest-Key, X-Digest-Signature et X-Digest-Timestamp, qui sont expliqués ci-dessous.

Exemple de requête

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"

En-têtes de requête

Clé	Type	Description
`X-Digest-Key`	string	Votre clé API HLR Lookups unique.	obligatoire
`X-Digest-Signature`	string	Une signature d'authentification unique (voir ci-dessous).	obligatoire
`X-Digest-Timestamp`	integer	Horodatage Unix actuel (voir également `GET /time`).	obligatoire

Construction de la signature

La X-Digest-Signature est créée à l'aide d'un hash HMAC SHA256, avec votre secret API comme clé partagée.

La chaîne à hasher est structurée comme suit :

ENDPOINT_PATH . UNIX_TIMESTAMP . REQUEST_METHOD . REQUEST_BODY

Le symbole . représente la concaténation de chaînes.

Composants de la signature Digest

Composant	Type	Description
`ENDPOINT_PATH`	string	L'endpoint API demandé, par exemple `/auth-test` en minuscules.
`UNIX_TIMESTAMP`	integer	Horodatage Unix actuel (doit être dans les 30 secondes). Voir `GET /time`.
`REQUEST_METHOD`	string	La méthode HTTP utilisée, par exemple `POST` ou `GET`.
`REQUEST_BODY`	string	Données du corps de la requête. Définir sur `null` pour les requêtes `GET`.

Exemples de code

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)

Remonter

Concepts

L'implémentation des requêtes HLR dans n'importe quel langage de programmation ou système via notre API REST HTTP est simple et efficace. Avec un processus d'intégration simple, vous pouvez commencer à interroger les réseaux mobiles en temps réel pour obtenir des informations instantanées sur la validité des numéros de téléphone, l'état de connectivité et les détails de routage.

Le choix de l'API appropriée dépend de votre cas d'usage spécifique. Si vous avez besoin de résultats de requête en temps réel pour des applications telles que la téléphonie VoIP, la détection de fraude ou le routage SMS, l'API synchrone est le meilleur choix. Cependant, si votre cas d'usage implique un traitement à haut volume, des requêtes en masse ou une vérification de données à grande échelle, l'API asynchrone offre des performances optimisées avec une efficacité de bande passante et des capacités de requête par lots.

Configurez l'API pour utiliser l'une de nos options de routage personnalisées afin d'optimiser la vitesse, la précision et le rapport coût-efficacité. Vous pouvez également stocker les résultats de requête dans des espaces de stockage pour faciliter le téléchargement de rapports CSV et JSON, ainsi que des analyses avancées via l'interface web.

API de requête HLR synchrone

Le point de terminaison POST /hlr-lookup traite un numéro de téléphone mobile (MSISDN) par requête et renvoie les résultats instantanément dans le corps de la réponse HTTP. Les résultats sont formatés en JSON et sont idéaux pour les applications en temps réel, notamment la validation de numéros mobiles, le routage d'appels et la livraison de messages SMS.

Un appel API synchrone consiste en une requête et une réponse HTTP directes. Votre système soumet un seul MSISDN (numéro mobile) par requête et reçoit une réponse immédiate contenant les résultats de requête HLR en temps réel au format JSON. Cette API est optimisée pour les cas d'usage nécessitant une vérification instantanée et des contrôles de connectivité, tels que la détection de fraude, le routage d'appels VoIP et l'optimisation de passerelles SMS.

API de consultation HLR asynchrone

Le point de terminaison POST /hlr-lookups est conçu pour le traitement en masse et à haut volume, vous permettant de soumettre jusqu'à 1,000 MSISDN par requête. Au lieu de renvoyer les résultats instantanément, cette API utilise des webhooks automatisés pour envoyer les résultats progressivement à votre serveur. Les résultats de requête sont renvoyés sous forme d'objets JSON via des rappels HTTP POST.

L'API asynchrone est optimisée pour la vitesse, l'efficacité et l'évolutivité. Elle élimine les problèmes de latence réseau associés aux appels synchrones, ce qui la rend idéale pour les entreprises nécessitant des requêtes à haut débit. Votre système soumet jusqu'à 1,000 MSISDN par requête, et notre plateforme les traite en parallèle, renvoyant les résultats à votre serveur via des webhooks HTTP par lots pouvant contenir jusqu'à 1,000 résultats par rappel.

SDK (Kits de Développement Logiciel)

Nos Kits de Développement Logiciel (SDK) pour PHP, NodeJS et Ruby simplifient le processus d'intégration, vous permettant de vous connecter à l'API HLR Lookups de manière efficace et avec un minimum d'effort.

Ces SDK fournissent des fonctions pré-construites, la gestion de l'authentification et des modèles de requêtes API structurés, réduisant le temps de développement et garantissant les meilleures pratiques.

Découvrez notre liste complète de SDK disponibles sur GitHub et commencez votre intégration dès aujourd'hui.

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

Voir sur 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   }

Voir sur 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)

Voir sur GitHub README.md

Remonter

POST/hlr-lookupprotégé

Effectue une requête HLR synchrone, fournissant en temps réel les données de connectivité et de portabilité des téléphones mobiles directement depuis les opérateurs réseau. Ce point de terminaison est idéal pour les scénarios de trafic en direct où les applications sensibles au temps nécessitent une vérification immédiate de l'accessibilité actuelle d'un numéro de téléphone (connecté) ou de son indisponibilité (éteint). De plus, il permet de distinguer les numéros actifs des numéros invalides, inconnus ou fictifs.

Pour le traitement en masse de grands volumes de données ne nécessitant pas de résultats instantanés, envisagez d'utiliser le POST /hlr-lookups, optimisé pour le traitement par lots à haute vitesse.

Si votre objectif principal est de récupérer les données de portabilité des numéros mobiles (MCCMNC) sans nécessiter le statut de connectivité en direct, le POST /mnp-lookup offre une alternative économique pour les requêtes de portabilité des numéros mobiles.

Requête Réponse de succès Réponse d'erreur Référence des statuts

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

Charge utile

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`msisdn`	string	Le numéro de téléphone mobile (MSISDN) à interroger, fourni au format international (par exemple, +14156226819 ou 0014156226819). Les indicatifs pays doivent être inclus.	null	obligatoire
`route`	string(3)	Un identifiant optionnel de trois caractères spécifiant la route pour cette requête. Définissez sur `null` ou omettez ce paramètre pour appliquer votre carte de routage personnalisée ou laisser notre système déterminer automatiquement la meilleure route pour cette requête.	null	facultatif
`storage`	string	Un identifiant de stockage optionnel spécifiant le rapport où les résultats seront stockés pour révision manuelle, analyse et reporting. Le système ajoute automatiquement un horodatage avec le mois en cours. Si omis ou défini sur `null`, le système regroupera automatiquement les résultats par mois à des fins de reporting.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`id`	string(12)	Un identifiant unique attribué à cette demande de consultation.	false
`msisdn`	string	Le numéro de téléphone mobile interrogé, formaté au format international (par exemple, +14156226819 ou 0014156226819).	false
`connectivity_status`	string	Indique si le statut de connectivité du numéro a été récupéré avec succès. Valeurs possibles : `CONNECTED` , `ABSENT` , `INVALID_MSISDN` ou `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Un code MCC (Mobile Country Code) et MNC (Mobile Network Code) de cinq ou six chiffres identifiant le réseau actuellement associé au numéro de téléphone.	true
`mcc`	string(3)	Un code MCC (Mobile Country Code) de trois chiffres identifiant le pays où le numéro de téléphone est enregistré.	true
`mnc`	string(2\|3)	Un code MNC (Mobile Network Code) de deux ou trois chiffres identifiant le réseau spécifique auquel appartient le numéro de téléphone.	true
`imsi`	string	L'identité internationale d'abonné mobile (IMSI), un identifiant unique pour la carte SIM associée à ce numéro. La disponibilité dépend de la configuration du réseau.	true
`msin`	string(10)	Le numéro d'identification d'abonnement mobile (MSIN) dans la base de données de l'opérateur mobile. La disponibilité dépend de la configuration du réseau.	true
`msc`	string(12)	Le centre de commutation mobile (MSC) gérant actuellement les communications de cet abonné. La disponibilité dépend de la configuration du réseau.	true
`original_network_name`	string	Le nom de l'opérateur réseau d'origine (natif) associé à ce numéro.	true
`original_country_name`	string	Le nom complet du pays où le numéro de téléphone mobile a été initialement enregistré, fourni en anglais.	true
`original_country_code`	string(2)	Le code pays ISO à deux caractères représentant le pays où le numéro de téléphone a été attribué initialement.	true
`original_country_prefix`	string	L'indicatif téléphonique international (code d'appel du pays) correspondant au pays d'origine du numéro de téléphone mobile.	true
`is_ported`	boolean	Indique si le numéro mobile a été porté de son réseau d'origine vers un autre opérateur.	true
`ported_network_name`	string	Le nom de l'opérateur réseau vers lequel le numéro mobile a été porté, le cas échéant.	true
`ported_country_name`	string	Le nom du pays vers lequel le numéro mobile a été porté, le cas échéant.	true
`ported_country_code`	string(2)	Le code pays ISO à deux caractères représentant le pays vers lequel le numéro mobile a été porté, le cas échéant.	true
`ported_country_prefix`	string	L'indicatif téléphonique international (code d'appel du pays) du pays vers lequel le numéro mobile a été porté, le cas échéant.	true
`is_roaming`	boolean	Indique si le numéro mobile est actuellement en itinérance sur un réseau étranger. La disponibilité du statut d'itinérance dépend de l'opérateur de réseau mobile.	true
`roaming_network_name`	string	Le nom du réseau sur lequel le numéro mobile est actuellement en itinérance, le cas échéant.	true
`roaming_country_name`	string	Le nom du pays où le numéro mobile est actuellement en itinérance, le cas échéant.	true
`roaming_country_code`	string(2)	Le code pays ISO à deux caractères du pays où le numéro mobile est actuellement en itinérance, le cas échéant.	true
`roaming_country_prefix`	string	L'indicatif téléphonique international (code d'appel du pays) du pays où le numéro mobile est actuellement en itinérance, le cas échéant.	true
`cost`	string	Une valeur décimale représentée sous forme de chaîne, indiquant le coût de la consultation en EUR.	true
`timestamp`	string	Un horodatage au format W3C incluant le fuseau horaire, spécifiant quand la consultation a été effectuée.	true
`storage`	string	Le nom de l'espace de stockage où les résultats de la consultation ont été enregistrés. Cela correspond aux noms de rapports et aux téléchargements CSV disponibles via l'interface web.	true
`route`	string(3)	Un identifiant de trois caractères indiquant la méthode de routage utilisée pour cette demande de consultation.	true
`processing_status`	string	Le résultat du traitement de la consultation. Valeurs possibles : `COMPLETED` (réussi), `REJECTED` (réseau inaccessible, aucun frais appliqué) ou `FAILED` (erreur survenue lors du traitement).	false
`error_code`	integer	Un code d'erreur interne optionnel fournissant des informations de diagnostic supplémentaires pour le support client.	true
`error_description`	string	Une brève explication du code d'erreur donné (le cas échéant) en texte brut anglais.	true
`data_source`	string	La source de données utilisée pour cette demande. Valeurs possibles : `LIVE_HLR` (requête HLR en temps réel) ou `MNP_DB` (base de données statique de portabilité des numéros mobiles). Consultez les options de routage pour plus de détails.	false
`routing_instruction`	string	Une chaîne délimitée par des deux-points décrivant l'instruction de routage utilisée dans la demande. Le premier composant est `STATIC` lorsque vous avez spécifié une route ou `AUTO` pour le routage automatique ; le deuxième composant est l'identifiant de la route, et pour les demandes de routage automatique, un troisième composant indique l'origine sur laquelle la décision de routage est basée (c'est-à-dire `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."
    ]
}

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Statut	Description
CONNECTED	Le numéro est valide et le terminal cible est actuellement connecté au réseau mobile. Les appels, SMS et autres services devraient atteindre le destinataire avec succès.
ABSENT	Le numéro est valide, mais le terminal cible est soit éteint, soit temporairement hors de portée du réseau. Les messages ou appels peuvent ne pas être délivrés tant que l'appareil ne se reconnecte pas au réseau.
INVALID_MSISDN	Le numéro est invalide ou n'est actuellement attribué à aucun abonné sur le réseau mobile. Les appels et messages vers ce numéro échoueront.
UNDETERMINED	Le statut de connectivité du numéro n'a pas pu être déterminé. Cela peut être dû à un numéro invalide, une réponse d'erreur SS7, ou une absence de connectivité avec l'opérateur réseau cible. Consultez le code d'erreur et son champ de description pour des diagnostics supplémentaires.

Remonter

POST/hlr-lookupsprotégé

Lance un lot de consultations HLR asynchrones, récupérant en temps réel les données de connectivité et de portabilité des téléphones mobiles auprès des opérateurs réseau. Les résultats sont transmis via webhooks à votre serveur. Cette méthode est optimisée pour le traitement de gros volumes de numéros ne nécessitant pas de réponses immédiates, comme le nettoyage et la vérification de bases de données. Pour les applications en temps réel comme le routage d'appels ou la livraison de SMS, privilégiez plutôt l'endpoint POST /hlr-lookup.

Cet endpoint est idéal pour le traitement en masse lorsque l'objectif est d'identifier les numéros de téléphone actuellement joignables (connectés) ou indisponibles (téléphone éteint) tout en filtrant les numéros invalides, non attribués ou fictifs. De plus, il fournit le statut de portabilité en temps réel (MCCMNC) ainsi que les détails de connectivité.

Avant d'utiliser cet endpoint, assurez-vous qu'une URL webhook est configurée pour recevoir les résultats de consultation de manière asynchrone. Vous pouvez configurer cela dans vos paramètres API.

Requête Réponse de succès Réponse d'erreur Webhooks Référence des statuts

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

Charge utile

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`msisdns`	array	Un tableau de numéros de téléphone mobile (MSISDN) au format international (par ex. +14156226819 ou 0014156226819). Vous pouvez inclure jusqu'à 1000 numéros par requête.	null	obligatoire
`route`	string(3)	Un identifiant optionnel de trois caractères spécifiant la route pour cette requête. Définissez sur `null` ou omettez ce paramètre pour appliquer votre carte de routage personnalisée ou laisser notre système déterminer automatiquement la meilleure route pour cette requête.	null	facultatif
`storage`	string	Un identifiant de stockage optionnel spécifiant le rapport où les résultats seront stockés pour révision manuelle, analyse et reporting. Le système ajoute automatiquement un horodatage avec le mois en cours. Si omis ou défini sur `null`, le système regroupera automatiquement les résultats par mois à des fins de reporting.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`accepted`	array	Une liste d'objets contenant des identifiants uniques et des MSISDN acceptés pour traitement.	false
`accepted_count`	integer	Le nombre total de MSISDN acceptés avec succès pour traitement.	false
`rejected`	array	Une liste d'objets contenant des identifiants uniques et des MSISDN rejetés pour traitement, généralement en raison de numéros invalides. Aucun frais ne s'applique aux entrées rejetées.	false
`rejected_count`	integer	Le nombre total de MSISDN rejetés en raison d'erreurs de validation.	false
`total_count`	integer	Le nombre total de MSISDN acceptés et rejetés qui ont été soumis pour traitement.	false
`cost`	string	Une valeur décimale représentée sous forme de chaîne, indiquant le coût total en EUR pour les consultations acceptées.	false
`storage`	string	Le nom du stockage où les résultats de consultation sont ajoutés, utilisé pour les rapports et les téléchargements CSV via l'interface web.	false
`route`	string(3\|4)	Un identifiant de trois ou quatre caractères spécifiant la route utilisée pour cette requête de consultation. Contient AUTO si un routage automatique basé sur les numéros a été demandé.	false
`webhook_urls`	array	Les URL webhook configurées dans vos paramètres API. Les résultats y sont renvoyés.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Traitement des Webhooks

Une fois soumis, notre plateforme commence le traitement des numéros de téléphone fournis et envoie les résultats à l'URL webhook précédemment spécifiée sur votre serveur. Les résultats sont transmis sous forme de requête HTTP POST avec un objet JSON dans le corps de la requête.

Authentification

Authentifiez le webhook en inspectant l'en-tête HTTP X-Signatures.

L'en-tête X-Signatures contient une liste de signatures séparées par des points-virgules. Chaque signature de la liste est générée à l'aide de l'un des secrets API configurés dans votre compte. Pour vérifier le webhook, générez un hash SHA-256 en utilisant votre clé API, votre secret et le corps HTTP brut, puis comparez-le aux signatures de la liste.

Une correspondance confirme que la requête est authentique et signée avec un secret que vous contrôlez.

Exemple de code

$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 requête est valide si l'une des signatures fournies dans l'en-tête correspond à un hash SHA256 calculé sur la chaîne concaténée de votre clé API, votre secret et le corps HTTP.

Confirmation de Réception

Votre serveur doit répondre avec un code de statut HTTP 200 OK pour confirmer la réception réussie. Si un autre code de réponse est renvoyé, qu'un délai d'expiration se produit (10 secondes) ou que tout autre problème de livraison survient, le système réessaiera automatiquement le webhook après une minute. Si la requête continue d'échouer, les nouvelles tentatives suivront une stratégie d'attente exponentielle, avec des tentatives ultérieures après 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutes.

Ce mécanisme de nouvelle tentative garantit une fiabilité maximale dans la livraison des résultats de recherche à votre infrastructure. Il minimise le risque de perte de données en raison de problèmes réseau temporaires ou d'indisponibilité du serveur.

Charge Utile du 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"
      }
   ]
}

Attributs de la charge utile du webhook

L'objet JSON contient un attribut type => HLR ainsi qu'un attribut results qui inclut une liste d'objets de consultation, comme documenté ci-dessous.

Nom	Type	Description	Nullable
`id`	string(12)	Un identifiant unique attribué à cette demande de consultation.	false
`msisdn`	string	Le numéro de téléphone mobile interrogé, formaté au format international (par exemple, +14156226819 ou 0014156226819).	false
`connectivity_status`	string	Indique si le statut de connectivité du numéro a été récupéré avec succès. Valeurs possibles : `CONNECTED` , `ABSENT` , `INVALID_MSISDN` ou `UNDETERMINED` .	false
`mccmnc`	string(5\|6)	Un code MCC (Mobile Country Code) et MNC (Mobile Network Code) de cinq ou six chiffres identifiant le réseau actuellement associé au numéro de téléphone.	true
`mcc`	string(3)	Un code MCC (Mobile Country Code) de trois chiffres identifiant le pays où le numéro de téléphone est enregistré.	true
`mnc`	string(2\|3)	Un code MNC (Mobile Network Code) de deux ou trois chiffres identifiant le réseau spécifique auquel appartient le numéro de téléphone.	true
`imsi`	string	L'identité internationale d'abonné mobile (IMSI), un identifiant unique pour la carte SIM associée à ce numéro. La disponibilité dépend de la configuration du réseau.	true
`msin`	string(10)	Le numéro d'identification d'abonnement mobile (MSIN) dans la base de données de l'opérateur mobile. La disponibilité dépend de la configuration du réseau.	true
`msc`	string(12)	Le centre de commutation mobile (MSC) gérant actuellement les communications de cet abonné. La disponibilité dépend de la configuration du réseau.	true
`original_network_name`	string	Le nom de l'opérateur réseau d'origine (natif) associé à ce numéro.	true
`original_country_name`	string	Le nom complet du pays où le numéro de téléphone mobile a été initialement enregistré, fourni en anglais.	true
`original_country_code`	string(2)	Le code pays ISO à deux caractères représentant le pays où le numéro de téléphone a été attribué initialement.	true
`original_country_prefix`	string	L'indicatif téléphonique international (code d'appel du pays) correspondant au pays d'origine du numéro de téléphone mobile.	true
`is_ported`	boolean	Indique si le numéro mobile a été porté de son réseau d'origine vers un autre opérateur.	true
`ported_network_name`	string	Le nom de l'opérateur réseau vers lequel le numéro mobile a été porté, le cas échéant.	true
`ported_country_name`	string	Le nom du pays vers lequel le numéro mobile a été porté, le cas échéant.	true
`ported_country_code`	string(2)	Le code pays ISO à deux caractères représentant le pays vers lequel le numéro mobile a été porté, le cas échéant.	true
`ported_country_prefix`	string	L'indicatif téléphonique international (code d'appel du pays) du pays vers lequel le numéro mobile a été porté, le cas échéant.	true
`is_roaming`	boolean	Indique si le numéro mobile est actuellement en itinérance sur un réseau étranger. La disponibilité du statut d'itinérance dépend de l'opérateur de réseau mobile.	true
`roaming_network_name`	string	Le nom du réseau sur lequel le numéro mobile est actuellement en itinérance, le cas échéant.	true
`roaming_country_name`	string	Le nom du pays où le numéro mobile est actuellement en itinérance, le cas échéant.	true
`roaming_country_code`	string(2)	Le code pays ISO à deux caractères du pays où le numéro mobile est actuellement en itinérance, le cas échéant.	true
`roaming_country_prefix`	string	L'indicatif téléphonique international (code d'appel du pays) du pays où le numéro mobile est actuellement en itinérance, le cas échéant.	true
`cost`	string	Une valeur décimale représentée sous forme de chaîne, indiquant le coût de la consultation en EUR.	true
`timestamp`	string	Un horodatage au format W3C incluant le fuseau horaire, spécifiant quand la consultation a été effectuée.	true
`storage`	string	Le nom de l'espace de stockage où les résultats de la consultation ont été enregistrés. Cela correspond aux noms de rapports et aux téléchargements CSV disponibles via l'interface web.	true
`route`	string(3)	Un identifiant de trois caractères indiquant la méthode de routage utilisée pour cette demande de consultation.	true
`processing_status`	string	Le résultat du traitement de la consultation. Valeurs possibles : `COMPLETED` (réussi), `REJECTED` (réseau inaccessible, aucun frais appliqué) ou `FAILED` (erreur survenue lors du traitement).	false
`error_code`	integer	Un code d'erreur interne optionnel fournissant des informations de diagnostic supplémentaires pour le support client.	true
`error_description`	string	Une brève explication du code d'erreur donné (le cas échéant) en texte brut anglais.	true
`data_source`	string	La source de données utilisée pour cette demande. Valeurs possibles : `LIVE_HLR` (requête HLR en temps réel) ou `MNP_DB` (base de données statique de portabilité des numéros mobiles). Consultez les options de routage pour plus de détails.	false
`routing_instruction`	string	Une chaîne délimitée par des deux-points décrivant l'instruction de routage utilisée dans la demande. Le premier composant est `STATIC` lorsque vous avez spécifié une route ou `AUTO` pour le routage automatique ; le deuxième composant est l'identifiant de la route, et pour les demandes de routage automatique, un troisième composant indique l'origine sur laquelle la décision de routage est basée (c'est-à-dire `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

Statut	Description
CONNECTED	Le numéro est valide et le terminal cible est actuellement connecté au réseau mobile. Les appels, SMS et autres services devraient atteindre le destinataire avec succès.
ABSENT	Le numéro est valide, mais le terminal cible est soit éteint, soit temporairement hors de portée du réseau. Les messages ou appels peuvent ne pas être délivrés tant que l'appareil ne se reconnecte pas au réseau.
INVALID_MSISDN	Le numéro est invalide ou n'est actuellement attribué à aucun abonné sur le réseau mobile. Les appels et messages vers ce numéro échoueront.
UNDETERMINED	Le statut de connectivité du numéro n'a pas pu être déterminé. Cela peut être dû à un numéro invalide, une réponse d'erreur SS7, ou une absence de connectivité avec l'opérateur réseau cible. Consultez le code d'erreur et son champ de description pour des diagnostics supplémentaires.

Remonter

POST/mnp-lookupprotégé

Effectue une interrogation MNP synchrone et fournit des informations sur la portabilité du numéro mobile et le réseau. Ce point de terminaison est adapté si votre objectif principal est d'extraire le MCCMNC actuel d'un numéro de téléphone mobile donné et d'identifier les réseaux d'origine et actuel en temps réel.

Pour le traitement en masse de grands volumes de données ne nécessitant pas de résultats instantanés, envisagez d'utiliser le POST /mnp-lookups, optimisé pour le traitement par lots à haute vitesse.

Les requêtes MNP déterminent de manière fiable la portabilité et les informations réseau, mais n'indiquent pas si le téléphone mobile cible est actuellement connecté à un réseau et joignable. Pour extraire des informations de connectivité en direct, veuillez utiliser le point de terminaison POST /hlr-lookup à la place.

Requête Réponse de succès Réponse d'erreur

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

Charge utile

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`msisdn`	string	Le numéro de téléphone mobile (MSISDN) à interroger, fourni au format international (par exemple, +14156226819 ou 0014156226819). Les indicatifs pays doivent être inclus.	null	obligatoire
`route`	string(3)	Un identifiant optionnel de trois caractères spécifiant la route pour cette requête. Définissez sur `null` ou omettez ce paramètre pour appliquer votre carte de routage personnalisée ou laisser notre système déterminer automatiquement la meilleure route pour cette requête.	null	facultatif
`storage`	string	Un identifiant de stockage optionnel spécifiant le rapport où les résultats seront stockés pour révision manuelle, analyse et reporting. Le système ajoute automatiquement un horodatage avec le mois en cours. Si omis ou défini sur `null`, le système regroupera automatiquement les résultats par mois à des fins de reporting.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`id`	string(12)	Un identifiant unique de 12 caractères pour cette interrogation.	false
`msisdn`	string	Le numéro de téléphone mobile évalué dans cette demande d'interrogation.	false
`query_status`	string	Indique si la récupération des informations de portabilité et de réseau a réussi. Les valeurs possibles sont `OK` ou `FAILED`.	false
`mccmnc`	string(5\|6)	Un code MCCMNC de cinq ou six caractères (combinaison du code pays mobile et du code réseau mobile) qui identifie le réseau auquel appartient actuellement le numéro de téléphone mobile.	true
`mcc`	string(3)	Un MCC de trois caractères (code pays mobile) représentant le pays associé au réseau actuel du numéro de téléphone mobile.	true
`mnc`	string(2\|3)	Un MNC de deux ou trois caractères (code réseau mobile) qui identifie l'opérateur réseau actuel du numéro de téléphone mobile.	true
`is_ported`	boolean	Indique si le numéro de téléphone a été porté de son réseau d'origine vers un nouvel opérateur.	true
`original_network_name`	string	Une chaîne arbitraire (en anglais) spécifiant le nom de l'opérateur réseau d'origine du numéro de téléphone mobile inspecté.	true
`original_country_name`	string	Une chaîne arbitraire (en anglais) indiquant le pays d'origine du numéro de téléphone mobile inspecté.	true
`original_country_code`	string(2)	Un code pays ISO à deux caractères représentant le pays d'origine du numéro de téléphone mobile inspecté.	true
`original_country_prefix`	string	L'indicatif téléphonique du pays d'origine associé au numéro de téléphone mobile inspecté.	true
`ported_network_name`	string	Spécifie l'opérateur réseau vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`ported_country_name`	string	Spécifie le pays vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`ported_country_code`	string(2)	Un code pays ISO à deux caractères représentant le pays vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`ported_country_prefix`	string	L'indicatif téléphonique du pays vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`extra`	string	Une chaîne arbitraire fournissant des détails supplémentaires facultatifs sur le numéro de téléphone.	true
`cost`	string	Une valeur décimale, représentée sous forme de chaîne, indiquant le coût en EUR pour cette interrogation.	true
`timestamp`	string	Un horodatage au format W3C, incluant les informations de fuseau horaire, indiquant quand l'interrogation a été effectuée.	true
`storage`	string	Le nom de stockage (ou nom de rapport) auquel les résultats de l'interrogation ont été ajoutés. Utilisé pour les téléchargements CSV et les rapports via l'interface web.	true
`route`	string(3)	Un identifiant de trois caractères spécifiant la route utilisée pour cette demande d'interrogation.	true
`error_code`	integer	Un code d'erreur interne facultatif fournissant un contexte supplémentaire pour le diagnostic du support client.	true

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

POST/mnp-lookupsprotégé

Lance un lot de requêtes MNP (portabilité des numéros mobiles) asynchrones, récupérant le MCCMNC actuel et identifiant les réseaux d'origine et actuels en temps réel. Les résultats sont transmis via webhooks à votre serveur. Cette méthode est optimisée pour le traitement de gros volumes de numéros ne nécessitant pas de réponses immédiates, comme le nettoyage et la vérification de bases de données. Pour les applications en temps réel comme le routage d'appels ou la livraison de SMS, privilégiez plutôt l'endpoint POST /mnp-lookup.

Les requêtes MNP déterminent de manière fiable la portabilité et les informations réseau, mais n'indiquent pas si le téléphone mobile cible est actuellement connecté à un réseau et joignable. Pour extraire des informations de connectivité en direct, veuillez utiliser le point de terminaison POST /hlr-lookups à la place.

Avant d'utiliser cet endpoint, assurez-vous qu'une URL webhook est configurée pour recevoir les résultats de consultation de manière asynchrone. Vous pouvez configurer cela dans vos paramètres API.

Requête Réponse de succès Réponse d'erreur Webhooks

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

Charge utile

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`msisdns`	array	Un tableau de numéros de téléphone mobile (MSISDN) au format international (par ex. +14156226819 ou 0014156226819). Vous pouvez inclure jusqu'à 1000 numéros par requête.	null	obligatoire
`route`	string(3)	Un identifiant optionnel de trois caractères spécifiant la route pour cette requête. Définissez sur `null` ou omettez ce paramètre pour appliquer votre carte de routage personnalisée ou laisser notre système déterminer automatiquement les meilleures routes pour cette demande.	null	facultatif
`storage`	string	Un identifiant de stockage optionnel spécifiant le rapport où les résultats seront stockés pour révision manuelle, analyse et reporting. Le système ajoute automatiquement un horodatage avec le mois en cours. Si omis ou défini sur `null`, le système regroupera automatiquement les résultats par mois à des fins de reporting.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`accepted`	array	Une liste d'objets contenant des identifiants uniques et des MSISDN acceptés pour traitement.	false
`accepted_count`	integer	Le nombre total de MSISDN acceptés avec succès pour traitement.	false
`rejected`	array	Une liste d'objets contenant des identifiants uniques et des MSISDN rejetés pour traitement, généralement en raison de numéros invalides. Aucun frais ne s'applique aux entrées rejetées.	false
`rejected_count`	integer	Le nombre total de MSISDN rejetés en raison d'erreurs de validation.	false
`total_count`	integer	Le nombre total de MSISDN acceptés et rejetés qui ont été soumis pour traitement.	false
`cost`	string	Une valeur décimale représentée sous forme de chaîne, indiquant le coût total en EUR pour les consultations acceptées.	false
`storage`	string	Le nom du stockage où les résultats de consultation sont ajoutés, utilisé pour les rapports et les téléchargements CSV via l'interface web.	false
`route`	string(3)	Un identifiant de trois caractères spécifiant la route utilisée pour cette demande d'interrogation.	false
`webhook_urls`	array	Les URL webhook configurées dans vos paramètres API. Les résultats y sont renvoyés.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Traitement des Webhooks

Une fois soumis, notre plateforme commence le traitement des numéros de téléphone fournis et envoie les résultats à l'URL webhook précédemment spécifiée sur votre serveur. Les résultats sont transmis sous forme de requête HTTP POST avec un objet JSON dans le corps de la requête.

Authentification

Authentifiez le webhook en inspectant l'en-tête HTTP X-Signatures.

L'en-tête X-Signatures contient une liste de signatures séparées par des points-virgules. Chaque signature de la liste est générée à l'aide de l'un des secrets API configurés dans votre compte. Pour vérifier le webhook, générez un hash SHA-256 en utilisant votre clé API, votre secret et le corps HTTP brut, puis comparez-le aux signatures de la liste.

Une correspondance confirme que la requête est authentique et signée avec un secret que vous contrôlez.

Exemple de code

$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 requête est valide si l'une des signatures fournies dans l'en-tête correspond à un hash SHA256 calculé sur la chaîne concaténée de votre clé API, votre secret et le corps HTTP.

Confirmation de Réception

Votre serveur doit répondre avec un code de statut HTTP 200 OK pour confirmer la réception réussie. Si un autre code de réponse est renvoyé, qu'un délai d'expiration se produit (10 secondes) ou que tout autre problème de livraison survient, le système réessaiera automatiquement le webhook après une minute. Si la requête continue d'échouer, les nouvelles tentatives suivront une stratégie d'attente exponentielle, avec des tentatives ultérieures après 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutes.

Ce mécanisme de nouvelle tentative garantit une fiabilité maximale dans la livraison des résultats de recherche à votre infrastructure. Il minimise le risque de perte de données en raison de problèmes réseau temporaires ou d'indisponibilité du serveur.

Charge Utile du 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
        }
    ]
}

Attributs de la charge utile du webhook

L'objet JSON contient un attribut type => MNP ainsi qu'un attribut results qui inclut une liste d'objets de consultation, comme documenté ci-dessous.

Nom	Type	Description	Nullable
`id`	string(12)	Un identifiant unique de 12 caractères pour cette interrogation.	false
`msisdn`	string	Le numéro de téléphone mobile évalué dans cette demande d'interrogation.	false
`query_status`	string	Indique si la récupération des informations de portabilité et de réseau a réussi. Les valeurs possibles sont `OK` ou `FAILED`.	false
`mccmnc`	string(5\|6)	Un code MCCMNC de cinq ou six caractères (combinaison du code pays mobile et du code réseau mobile) qui identifie le réseau auquel appartient actuellement le numéro de téléphone mobile.	true
`mcc`	string(3)	Un MCC de trois caractères (code pays mobile) représentant le pays associé au réseau actuel du numéro de téléphone mobile.	true
`mnc`	string(2\|3)	Un MNC de deux ou trois caractères (code réseau mobile) qui identifie l'opérateur réseau actuel du numéro de téléphone mobile.	true
`is_ported`	boolean	Indique si le numéro de téléphone a été porté de son réseau d'origine vers un nouvel opérateur.	true
`original_network_name`	string	Une chaîne arbitraire (en anglais) spécifiant le nom de l'opérateur réseau d'origine du numéro de téléphone mobile inspecté.	true
`original_country_name`	string	Une chaîne arbitraire (en anglais) indiquant le pays d'origine du numéro de téléphone mobile inspecté.	true
`original_country_code`	string(2)	Un code pays ISO à deux caractères représentant le pays d'origine du numéro de téléphone mobile inspecté.	true
`original_country_prefix`	string	L'indicatif téléphonique du pays d'origine associé au numéro de téléphone mobile inspecté.	true
`ported_network_name`	string	Spécifie l'opérateur réseau vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`ported_country_name`	string	Spécifie le pays vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`ported_country_code`	string(2)	Un code pays ISO à deux caractères représentant le pays vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`ported_country_prefix`	string	L'indicatif téléphonique du pays vers lequel le numéro de téléphone mobile inspecté a été porté, le cas échéant.	true
`extra`	string	Une chaîne arbitraire fournissant des détails supplémentaires facultatifs sur le numéro de téléphone.	true
`cost`	string	Une valeur décimale, représentée sous forme de chaîne, indiquant le coût en EUR pour cette interrogation.	true
`timestamp`	string	Un horodatage au format W3C, incluant les informations de fuseau horaire, indiquant quand l'interrogation a été effectuée.	true
`storage`	string	Le nom de stockage (ou nom de rapport) auquel les résultats de l'interrogation ont été ajoutés. Utilisé pour les téléchargements CSV et les rapports via l'interface web.	true
`route`	string(3)	Un identifiant de trois caractères spécifiant la route utilisée pour cette demande d'interrogation.	true
`error_code`	integer	Un code d'erreur interne facultatif fournissant un contexte supplémentaire pour le diagnostic du support client.	true

Remonter

POST/nt-lookupprotégé

Lance une requête synchrone de type de numéro (NT). Ce point de terminaison est idéal si votre objectif principal est de déterminer en temps réel si les numéros de téléphone fournis appartiennent à des plages de numérotation fixes, mobiles, à tarification majorée, VoIP, de radiomessagerie ou autres.

Les requêtes NT détectent de manière fiable le type de numéro de téléphone, mais n'indiquent pas si le numéro cible est actuellement connecté à un réseau et joignable. Pour obtenir des informations de connectivité en temps réel, veuillez utiliser le point de terminaison POST /hlr-lookup.

Si votre cas d'usage nécessite des informations précises sur le réseau et la portabilité (MCCMNC) mais pas le statut de connectivité en temps réel, veuillez utiliser le point de terminaison POST /mnp-lookup pour les requêtes de portabilité des numéros mobiles.

Requête Réponse de succès Réponse d'erreur Référence des types

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

Charge utile

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`number`	string	Un numéro de téléphone au format international (par exemple +4989702626 ou 004989702626).	null	mandatory
`route`	string(3)	Un identifiant optionnel de trois caractères spécifiant l'itinéraire pour cette requête. Définissez sur `null` ou omettez ce paramètre pour appliquer votre carte de routage personnalisée ou laisser notre système déterminer automatiquement les meilleurs itinéraires pour cette requête.	null	facultatif
`storage`	string	Un identifiant de stockage optionnel spécifiant le rapport où les résultats seront stockés pour révision manuelle, analyse et reporting. Le système ajoute automatiquement un horodatage avec le mois en cours. Si omis ou défini sur `null`, le système regroupera automatiquement les résultats par mois à des fins de reporting.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`id`	string(12)	Un identifiant unique attribué à cette demande de consultation.	false
`number`	string	Le numéro de téléphone qui a été évalué lors de cette requête de consultation.	false
`number_type`	string	Le type de numéro détecté. Les valeurs possibles incluent : `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indique si les informations sur le type de numéro ont été obtenues avec succès. Renvoie `OK` en cas de succès, ou `FAILED` si la consultation a échoué.	false
`is_valid`	boolean	Indique si le numéro de téléphone est syntaxiquement valide.	true
`invalid_reason`	string	Un message en texte brut en anglais précisant pourquoi le numéro de téléphone est considéré comme invalide (par exemple "too short" ou "invalid prefix"), ou `null` si le numéro est valide.	true
`is_possibly_ported`	boolean	Indique si le numéro de téléphone a pu être porté de son opérateur d'origine vers un autre opérateur. Pour obtenir des informations définitives sur la portabilité, utilisez les consultations MNP.	true
`is_vanity_number`	boolean	Indique si le numéro de téléphone est un numéro mnémonique, c'est-à-dire qu'il contient des caractères alphabétiques.	true
`qualifies_for_hlr_lookup`	boolean	Indique si le numéro de téléphone est éligible pour des requêtes supplémentaires via les consultations HLR.	true
`mccmnc`	string(5\|6)	Une chaîne de cinq ou six caractères représentant le tuple MCCMNC (code pays mobile et code réseau mobile) qui identifie le réseau d'origine du numéro de téléphone mobile.	true
`mcc`	string(3)	Une chaîne de trois caractères représentant le MCC (code pays mobile) qui identifie le pays associé au réseau mobile d'origine du numéro de téléphone.	true
`mnc`	string(2\|3)	Une chaîne de deux ou trois caractères représentant le MNC (code réseau mobile) qui identifie l'opérateur de réseau mobile d'origine du numéro de téléphone.	true
`original_network_name`	string	Une chaîne de texte brut arbitraire en anglais précisant le nom de l'opérateur de réseau d'origine du numéro de téléphone mobile inspecté.	true
`original_country_name`	string	Une chaîne de texte brut arbitraire en anglais précisant le pays d'origine associé au numéro de téléphone mobile inspecté.	true
`original_country_code`	string(2)	Un code pays ISO à deux caractères indiquant le pays d'origine du numéro de téléphone mobile inspecté.	true
`regions`	array	Une liste de chaînes lisibles en anglais qui précisent la ou les régions géographiques associées à ce numéro de téléphone.	true
`timezones`	array	Une liste de fuseaux horaires (au format Olson) associés à ce numéro de téléphone.	true
`info_text`	string	Une chaîne arbitraire pouvant contenir des informations supplémentaires sur le numéro de téléphone.	true
`cost`	string	Une valeur décimale représentée sous forme de chaîne, indiquant le coût (en EUR) de cette consultation.	true
`timestamp`	string	Un horodatage au format W3C (incluant le fuseau horaire) indiquant quand la consultation a été effectuée.	true
`storage`	string	Spécifie le nom de stockage où les résultats de consultation ont été ajoutés. Cela correspond au nom de rapport utilisé pour les téléchargements CSV et les analyses via l'interface web.	true
`route`	string(3)	Un identifiant de trois caractères spécifiant la route utilisée pour cette demande d'interrogation.	true

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Type	Description
LANDLINE	Numéro de téléphone fixe.
MOBILE	Numéro de téléphone mobile. Éligible aux requêtes HLR pour obtenir des informations supplémentaires sur l'état de connexion, le réseau, la portabilité et l'itinérance.
MOBILE_OR_LANDLINE	Numéro de téléphone fixe ou mobile. Peut être éligible aux requêtes HLR.
TOLL_FREE	Numéro de téléphone gratuit.
PREMIUM_RATE	Numéro de téléphone surtaxé avec frais supplémentaires.
SHARED_COST	Numéro de téléphone à coût partagé. Généralement moins cher que les numéros surtaxés.
VOIP	Numéro de téléphone VoIP. Inclut les numéros TSoIP (Telephony Service over IP).
PAGER	Numéro de téléavertisseur. Généralement sans fonctionnalité vocale.
UAN	Numéro d'accès universel (numéro d'entreprise). Peut être redirigé vers des bureaux spécifiques mais permet d'utiliser un seul numéro pour l'entreprise.
VOICEMAIL	Numéro de messagerie vocale.
UNKNOWN	Le type de numéro n'a pas pu être déterminé.

Remonter

POST/nt-lookups protégé

Ce point de terminaison déclenche une série de recherches asynchrones de type de numéro dont les résultats sont renvoyés à votre serveur via webhook. Il convient si votre objectif principal est de déterminer si des numéros de téléphone donnés appartiennent à des plages de numérotation fixes, mobiles, à tarification majorée, VoIP, messagerie ou autres. Optimisé pour le traitement rapide de grands volumes de numéros, ce point de terminaison est idéal pour les opérations en masse (par exemple, l'assainissement de bases de données). Pour le trafic en temps réel et les cas d'usage critiques en termes de temps, veuillez utiliser le point de terminaison POST /nt-lookup à la place.

Vous devez spécifier une URL de webhook dans vos paramètres API comme prérequis pour invoquer ce point de terminaison.

Requête Réponse de succès Réponse d'erreur Webhooks Référence des types

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

Charge utile

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`numbers`	array	Un tableau de numéros de téléphone au format international (par exemple +14156226819 ou 004989702626). Un maximum de 1000 numéros peut être inclus par requête.	null	obligatoire
`route`	string(3)	Un identifiant optionnel à trois caractères spécifiant la route pour cette recherche. Définissez sur `null` ou omettez ce paramètre pour appliquer votre carte de routage personnalisée ou laisser notre système déterminer automatiquement la meilleure route pour cette requête.	null	facultatif
`storage`	string	Un identifiant de stockage optionnel spécifiant le rapport où les résultats seront stockés pour révision manuelle, analyse et reporting. Le système ajoute automatiquement un horodatage avec le mois en cours. Si omis ou défini sur `null`, le système regroupera automatiquement les résultats par mois à des fins de reporting.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`accepted`	array	Un tableau d'objets, chacun contenant un identifiant unique et un numéro de téléphone qui a été accepté pour traitement.	false
`accepted_count`	integer	Le nombre total de numéros de téléphone acceptés pour traitement.	false
`rejected`	array	Un tableau d'objets, chacun contenant un identifiant unique et un numéro de téléphone qui a été rejeté pour traitement. Généralement, ces numéros sont invalides et aucun frais n'est appliqué.	false
`rejected_count`	integer	Le nombre total de numéros de téléphone qui ont été rejetés pour traitement.	false
`total_count`	integer	Le nombre total de numéros de téléphone acceptés et rejetés qui ont été soumis pour traitement.	false
`cost`	string	Une chaîne représentant une valeur décimale qui indique le coût en EUR pour ces recherches.	false
`storage`	string	Le nom du stockage (rapport) où les résultats de recherche ont été ajoutés. Ce nom est utilisé pour les téléchargements CSV et les analyses via l'interface web.	false
`route`	string(3)	Un identifiant à trois caractères qui spécifie la route utilisée pour cette requête de recherche.	false
`webhook_urls`	array	Les URL webhook configurées dans vos paramètres API. Les résultats y sont renvoyés.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Traitement des Webhooks

Une fois soumis, notre plateforme commence le traitement des numéros de téléphone fournis et envoie les résultats à l'URL webhook précédemment spécifiée sur votre serveur. Les résultats sont transmis sous forme de requête HTTP POST avec un objet JSON dans le corps de la requête.

Authentification

Authentifiez le webhook en inspectant l'en-tête HTTP X-Signatures.

L'en-tête X-Signatures contient une liste de signatures séparées par des points-virgules. Chaque signature de la liste est générée à l'aide de l'un des secrets API configurés dans votre compte. Pour vérifier le webhook, générez un hash SHA-256 en utilisant votre clé API, votre secret et le corps HTTP brut, puis comparez-le aux signatures de la liste.

Une correspondance confirme que la requête est authentique et signée avec un secret que vous contrôlez.

Exemple de code

$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 requête est valide si l'une des signatures fournies dans l'en-tête correspond à un hash SHA256 calculé sur la chaîne concaténée de votre clé API, votre secret et le corps HTTP.

Confirmation de Réception

Votre serveur doit répondre avec un code de statut HTTP 200 OK pour confirmer la réception réussie. Si un autre code de réponse est renvoyé, qu'un délai d'expiration se produit (10 secondes) ou que tout autre problème de livraison survient, le système réessaiera automatiquement le webhook après une minute. Si la requête continue d'échouer, les nouvelles tentatives suivront une stratégie d'attente exponentielle, avec des tentatives ultérieures après 2, 4, 8, 16, 32, 64, 128, 256, 512, 1024 minutes.

Ce mécanisme de nouvelle tentative garantit une fiabilité maximale dans la livraison des résultats de recherche à votre infrastructure. Il minimise le risque de perte de données en raison de problèmes réseau temporaires ou d'indisponibilité du serveur.

Charge Utile du 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"
      }
   ]
}

Attributs de la charge utile du webhook

L'objet JSON contient un attribut type => NT ainsi qu'un attribut results qui inclut une liste d'objets de consultation, comme documenté ci-dessous.

Nom	Type	Description	Nullable
`id`	string(12)	Un identifiant unique attribué à cette demande de consultation.	false
`number`	string	Le numéro de téléphone qui a été évalué lors de cette requête de consultation.	false
`number_type`	string	Le type de numéro détecté. Les valeurs possibles incluent : `LANDLINE` , `MOBILE` , `MOBILE_OR_LANDLINE` , `TOLL_FREE` , `PREMIUM_RATE` , `SHARED_COST` , `VOIP` , `PAGER` , `UAN` , `VOICEMAIL` , `UNKNOWN` .	false
`query_status`	string	Indique si les informations sur le type de numéro ont été obtenues avec succès. Renvoie `OK` en cas de succès, ou `FAILED` si la consultation a échoué.	false
`is_valid`	boolean	Indique si le numéro de téléphone est syntaxiquement valide.	true
`invalid_reason`	string	Un message en texte brut en anglais précisant pourquoi le numéro de téléphone est considéré comme invalide (par exemple "too short" ou "invalid prefix"), ou `null` si le numéro est valide.	true
`is_possibly_ported`	boolean	Indique si le numéro de téléphone a pu être porté de son opérateur d'origine vers un autre opérateur. Pour obtenir des informations définitives sur la portabilité, utilisez les consultations MNP.	true
`is_vanity_number`	boolean	Indique si le numéro de téléphone est un numéro mnémonique, c'est-à-dire qu'il contient des caractères alphabétiques.	true
`qualifies_for_hlr_lookup`	boolean	Indique si le numéro de téléphone est éligible pour des requêtes supplémentaires via les consultations HLR.	true
`mccmnc`	string(5\|6)	Une chaîne de cinq ou six caractères représentant le tuple MCCMNC (code pays mobile et code réseau mobile) qui identifie le réseau d'origine du numéro de téléphone mobile.	true
`mcc`	string(3)	Une chaîne de trois caractères représentant le MCC (code pays mobile) qui identifie le pays associé au réseau mobile d'origine du numéro de téléphone.	true
`mnc`	string(2\|3)	Une chaîne de deux ou trois caractères représentant le MNC (code réseau mobile) qui identifie l'opérateur de réseau mobile d'origine du numéro de téléphone.	true
`original_network_name`	string	Une chaîne de texte brut arbitraire en anglais précisant le nom de l'opérateur de réseau d'origine du numéro de téléphone mobile inspecté.	true
`original_country_name`	string	Une chaîne de texte brut arbitraire en anglais précisant le pays d'origine associé au numéro de téléphone mobile inspecté.	true
`original_country_code`	string(2)	Un code pays ISO à deux caractères indiquant le pays d'origine du numéro de téléphone mobile inspecté.	true
`regions`	array	Une liste de chaînes lisibles en anglais qui précisent la ou les régions géographiques associées à ce numéro de téléphone.	true
`timezones`	array	Une liste de fuseaux horaires (au format Olson) associés à ce numéro de téléphone.	true
`info_text`	string	Une chaîne arbitraire pouvant contenir des informations supplémentaires sur le numéro de téléphone.	true
`cost`	string	Une valeur décimale représentée sous forme de chaîne, indiquant le coût (en EUR) de cette consultation.	true
`timestamp`	string	Un horodatage au format W3C (incluant le fuseau horaire) indiquant quand la consultation a été effectuée.	true
`storage`	string	Spécifie le nom de stockage où les résultats de consultation ont été ajoutés. Cela correspond au nom de rapport utilisé pour les téléchargements CSV et les analyses via l'interface web.	true
`route`	string(3)	Un identifiant de trois caractères spécifiant la route utilisée pour cette demande d'interrogation.	true

Type	Description
LANDLINE	Numéro de téléphone fixe.
MOBILE	Numéro de téléphone mobile. Éligible aux requêtes HLR pour obtenir des informations supplémentaires sur l'état de connexion, le réseau, la portabilité et l'itinérance.
MOBILE_OR_LANDLINE	Numéro de téléphone fixe ou mobile. Peut être éligible aux requêtes HLR.
TOLL_FREE	Numéro de téléphone gratuit.
PREMIUM_RATE	Numéro de téléphone surtaxé avec frais supplémentaires.
SHARED_COST	Numéro de téléphone à coût partagé. Généralement moins cher que les numéros surtaxés.
VOIP	Numéro de téléphone VoIP. Inclut les numéros TSoIP (Telephony Service over IP).
PAGER	Numéro de téléavertisseur. Généralement sans fonctionnalité vocale.
UAN	Numéro d'accès universel (numéro d'entreprise). Peut être redirigé vers des bureaux spécifiques mais permet d'utiliser un seul numéro pour l'entreprise.
VOICEMAIL	Numéro de messagerie vocale.
UNKNOWN	Le type de numéro n'a pas pu être déterminé.

Remonter

GET/routeprotégé

Récupère la route qui sera automatiquement sélectionnée lorsque vous effectuez une recherche HLR sans spécifier le paramètre route.

La sélection automatique de la route est basée sur la carte de routage récupérable via le point de terminaison GET /hlr-coverage, qui est principalement dérivée de GET /routing-map. Vous pouvez personnaliser votre carte de routage et définir des règles personnalisées dans vos paramètres de compte.

Requête Réponse de succès Réponse d'erreur

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`msisdn`	string	Le MSISDN pour lequel récupérer les informations de routage automatiquement sélectionnées.	null	obligatoire

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`route`	string	La route recommandée.	false
`confidence_level`	string	Le niveau de confiance avec lequel cette route a été sélectionnée, c'est-à-dire `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`.	false
`mccmnc`	string	Le MCCMNC basé sur le plan de numérotation pour ce numéro.	false
`origin`	string	L'origine sur laquelle la décision de routage est basée, c'est-à-dire `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."
    ]
}

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/routesprotégé

Ce point de terminaison renvoie une liste des routes HLR, MNP et NT disponibles. Chaque route, ainsi que ses fonctionnalités et limitations, est expliquée sur la page détails du routage.

Requête Réponse de succès Réponse d'erreur

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

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`routes`	object	Un objet contenant les routes regroupées par type de route.	false
`HLR\|MNP\|NT`	string[]	Contient une liste d'identifiants de route.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/routing-mapprotégé

Récupère la configuration de routage automatisé actuellement appliquée aux recherches HLR de votre compte. Cette configuration par défaut est utilisée chaque fois que vous soumettez des recherches HLR sans spécifier de paramètre route. Vous pouvez personnaliser votre carte de routage et créer des règles personnalisées dans vos paramètres de compte.

La hiérarchie de configuration s'applique en cascade depuis les règles au niveau pays vers les règles au niveau MCCMNC, et enfin vers les correspondances de préfixes de numéros de téléphone individuels. En pratique, cela signifie que les correspondances de préfixes de numéros de téléphone individuels ont la priorité sur les affectations MCCMNC conflictuelles, qui à leur tour prévalent sur les règles au niveau pays. Veuillez noter que le repli MNP remplace toute règle personnalisée conflictuelle lorsqu'il est activé.

Requête Réponse de succès Réponse d'erreur

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`default_route`	string	La route par défaut utilisée lorsqu'aucune option de routage préférée ne peut être déterminée pour un MSISDN et qu'aucune règle de routage personnalisée ne s'applique.	false
`mnp_fallback`	boolean	Indique si le repli MNP est activé. Lorsqu'il est activé et que les requêtes HLR ne sont pas prises en charge par un réseau (statut de connectivité indisponible), le système effectuera une recherche MNP à la place.	false
`mccmncs`	array	Une correspondance des codes MCCMNC avec leurs routes sélectionnées automatiquement. Lors de l'exécution d'une recherche HLR pour un numéro dans un MCCMNC donné, la route correspondante est utilisée.	false
`mccmnc`	string(5\|6)	Un MCCMNC de cinq ou six caractères (combinaison du code pays mobile et du code réseau mobile) identifiant l'opérateur de réseau mobile.	false
`countrycode`	string(2)	Un code pays ISO à deux caractères, identifiant le pays du réseau.	false
`route`	string(3)	La route sélectionnée pour le réseau.	false
`mno`	string	La marque commerciale sous laquelle ce réseau opère.	false
`confidence`	string	Le niveau de confiance avec lequel la sélection a été effectuée. Les valeurs possibles sont : HIGH, NORMAL, LOW, MNP_REDIRECT. Dans ce dernier cas, le système redirige le trafic vers ce réseau vers MNP, si ce comportement est activé dans votre compte. Sinon, il utilise la route par défaut du compte.	false
`origin`	string	L'origine sur laquelle la sélection est basée. Les valeurs possibles sont : `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	Une liste de règles de routage personnalisées basées sur les préfixes configurées dans votre compte, le cas échéant.	false
`countrycode`	string(2)	Un code pays ISO à deux caractères, identifiant le pays du préfixe.	false
`cns`	string	Le préfixe auquel la règle de routage s'applique.	false
`route`	string(3)	La route sélectionnée pour le préfixe.	false
`mccmnc`	string(5\|6)	Un MCCMNC de cinq ou six caractères (combinaison du code pays mobile et du code réseau mobile) identifiant l'opérateur de réseau mobile.	true
`mno`	string	La marque commerciale sous laquelle ce réseau opère.	true
`countries`	array	Une liste de règles personnalisées basées sur les pays configurées dans votre compte, le cas échéant.	false
`countrycode`	string(2)	Un code pays ISO à deux caractères, identifiant le pays.	false
`route`	string(3)	La route sélectionnée pour le pays.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/hlr-coverage protégé

Fournit des informations sur la couverture HLR pour faciliter la prise de décision basée sur les données. Ce point de terminaison vous aide à analyser les options de routage HLR en temps réel à travers les réseaux mobiles, à identifier les chemins les plus efficaces pour vos régions cibles et à configurer votre routage automatique.

Les routes recommandées par GET /route sont basées sur les données de couverture récupérées ici. Les données de couverture sont également disponibles sur la page couverture réseau. Vous pouvez personnaliser davantage votre carte de routage et définir des règles dans vos paramètres de compte.

Nous vous recommandons de vous familiariser avec ce guide pour faciliter l'interprétation des résultats.

Requête Réponse de succès Réponse d'erreur Référence des statuts

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`countrycode`	string(2)	Un code pays ISO à deux lettres obligatoire utilisé pour filtrer les résultats, ne renvoyant que les enregistrements associés au pays spécifié.	null	obligatoire
`sample_size`	string	Un paramètre optionnel spécifiant une taille d'échantillon. Les valeurs possibles sont `LARGE`, `MEDIUM`, `SMALL`. Les échantillons plus grands couvrent une période plus longue, les échantillons plus petits couvrent une période très récente.	LARGE	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`name`	string	Le nom du pays sélectionné en anglais.	false
`countrycode`	string(2)	Le code pays ISO à deux caractères du pays sélectionné.	false
`prefix`	string	Le préfixe de numérotation internationale du pays sélectionné.	false
`mccs`	string[]	Une liste de MCC (codes pays mobile) associés au pays sélectionné.	false
`carriers`	object[]	Une liste d'objets opérateurs avec des métriques de connectivité spécifiques aux routes.	false
`mno`	string	Le nom de l'opérateur de réseau mobile en anglais.	false
`mccmnc`	string	Le MCCMNC de l'opérateur de réseau mobile.	false
`mcc`	string	Le MCC (code pays mobile) de l'opérateur de réseau mobile.	false
`mnc`	string	Le MNC (code réseau mobile) de l'opérateur de réseau mobile.	false
`routes`	object[]	Une liste de résultats de connectivité spécifiques aux routes.	false
`route`	string	La route à laquelle s'appliquent les informations de connectivité.	false
`selected`	bool	Indique s'il s'agit de la route sélectionnée pour le routage automatisé.	false
`selection_confidence`	string	Le niveau de confiance avec lequel cette route a été sélectionnée, c'est-à-dire `LOW`, `NORMAL`, `HIGH`, `MNP_FALLBACK`. Contient null si ce n'est pas la route sélectionnée.	true
`n`	int	Le nombre total de requêtes dans cet échantillon.	false
`CONNECTED`	int	Le nombre de requêtes HLR ayant renvoyé un statut CONNECTED.	false
`CONNECTED_PCT`	float	Le pourcentage de requêtes HLR ayant renvoyé un statut CONNECTED.	false
`ABSENT`	int	Le nombre de requêtes HLR ayant renvoyé un statut ABSENT.	false
`ABSENT_PCT`	float	Le pourcentage de requêtes HLR ayant renvoyé un statut ABSENT.	false
`INVALID_MSISDN`	int	Le nombre de requêtes HLR ayant renvoyé un statut INVALID_MSISDN.	false
`INVALID_MSISDN_PCT`	float	Le pourcentage de requêtes HLR ayant renvoyé un statut INVALID_MSISDN.	false
`UNDETERMINED`	int	Le nombre de requêtes HLR ayant renvoyé un statut UNDETERMINED.	false
`UNDETERMINED_PCT`	float	Le pourcentage de requêtes HLR ayant renvoyé un statut UNDETERMINED.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Statut	Description
CONNECTED	Le numéro est valide et le terminal cible est actuellement connecté au réseau mobile. Les appels, SMS et autres services devraient atteindre le destinataire avec succès.
ABSENT	Le numéro est valide, mais le terminal cible est soit éteint, soit temporairement hors de portée du réseau. Les messages ou appels peuvent ne pas être délivrés tant que l'appareil ne se reconnecte pas au réseau.
INVALID_MSISDN	Le numéro est invalide ou n'est actuellement attribué à aucun abonné sur le réseau mobile. Les appels et messages vers ce numéro échoueront.
UNDETERMINED	Le statut de connectivité du numéro n'a pas pu être déterminé. Cela peut être dû à un numéro invalide, une réponse d'erreur SS7, ou une absence de connectivité avec l'opérateur réseau cible. Consultez le code d'erreur et son champ de description pour des diagnostics supplémentaires.

Remonter

GET/mnp-coverageprotégé

Ce point de terminaison renvoie une liste d'opérateurs de réseaux mobiles, accompagnés de leurs identifiants MCCMNC correspondants, actuellement pris en charge pour les recherches de portabilité des numéros mobiles.

Requête Réponse de succès Réponse d'erreur

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`countrycode`	string(2)	Un code pays ISO à deux lettres optionnel utilisé pour filtrer les résultats MCCMNC, ne renvoyant que les données pertinentes pour le pays spécifié.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`items[]`	array	Une liste d'opérateurs de réseaux mobiles.	false
`country_name`	string	Le nom du pays en anglais.	false
`country_code`	string(2)	Un code pays ISO à deux lettres.	false
`mccmnc`	string(5\|6)	Un MCCMNC de cinq ou six caractères (combinaison du code pays mobile et du code réseau mobile) identifiant l'opérateur de réseau mobile.	false
`mcc`	string(3)	Un MCC de trois caractères (code pays mobile) représentant le pays du réseau.	false
`mnc`	string(2\|3)	Un MNC de deux ou trois caractères (code réseau mobile) représentant l'opérateur de réseau mobile spécifique.	false
`brand`	string	La marque commerciale sous laquelle ce réseau opère.	true
`operator`	string	La raison sociale de l'opérateur de réseau mobile.	true

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/price-listprotégé

Ce point de terminaison renvoie une liste de pays où seules les recherches MNP sont prises en charge, et les requêtes HLR ne sont pas disponibles pour ces destinations.

Requête Réponse de succès Réponse d'erreur

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

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`countries`	string[]	Une liste de codes pays ISO à deux caractères.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/mccmncsprotégé

Ce point de terminaison renvoie une liste complète des opérateurs de réseaux mobiles avec leurs identifiants MCCMNC correspondants et des informations contextuelles supplémentaires.

Requête Réponse de succès Réponse d'erreur

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`countrycode`	string(2)	Un code pays ISO à deux lettres optionnel utilisé pour filtrer les résultats MCCMNC, ne renvoyant que les enregistrements associés au pays spécifié.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`items`	object[]	Une liste d'opérateurs de réseaux mobiles.	false
`country_name`	string	Le nom complet du pays en anglais.	false
`country_code`	string(2)	Un code pays ISO à deux lettres représentant le pays de l'opérateur mobile.	false
`mccmnc`	string(5\|6)	Une chaîne de cinq ou six caractères représentant le MCCMNC, qui identifie de manière unique l'opérateur de réseau mobile.	false
`mcc`	string(3)	Un code pays mobile (MCC) à trois caractères qui identifie le pays où le réseau mobile opère.	false
`mnc`	string(2\|3)	Un code réseau mobile (MNC) à deux ou trois caractères qui spécifie le réseau mobile au sein du MCC donné.	false
`brand`	string	Le nom de marque commercial sous lequel le réseau opère et est reconnu par les consommateurs.	true
`operator`	string	Le nom officiel de l'opérateur de réseau mobile, généralement l'entité juridique qui gère le réseau.	true
`parent_mccmnc`	string(5\|6)	Une chaîne de cinq ou six caractères représentant le MCCMNC de l'opérateur de réseau mobile parent, le cas échéant.	true

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/priceprotégé

Ce point de terminaison renvoie le prix d'une consultation HLR, MNP ou NT.

Requête Réponse de succès Réponse d'erreur

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

Paramètres de requête

Clé	Type	Description	Par défaut	Obligatoire
`msisdn`	string	Le numéro de téléphone pour lequel récupérer le prix. Au format international.	null	obligatoire
`route_type`	string	Le type de route, c'est-à-dire `HLR`, `MNP`, `NT`.	null	obligatoire
`route`	string(3)	La route pour laquelle le prix doit être calculé. Par défaut, la route déterminée par le routage automatique.	null	facultatif

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`price`	object	Un objet contenant les détails de tarification.	false
`amount`	string	Le montant en EUR.	false
`msisdn`	string	Le MSISDN auquel ce prix s'applique.	false
`route_type`	string(2\|3)	Le type de route auquel ce prix s'applique.	false
`route`	string(3)	La route à laquelle ce prix s'applique.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/price-listprotégé

Ce point de terminaison renvoie la tarification de votre compte.

Requête Réponse de succès Réponse d'erreur

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

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`pricing`	object[]	Une liste d'objets contenant les informations tarifaires.	false
`route`	string	La route à laquelle cette tarification s'applique.	false
`countrycode`	string	Le code pays ISO à deux caractères auquel cette tarification s'applique pour la route correspondante, le cas échéant.	true
`countryname`	string	Le nom du pays en anglais correspondant au code pays, le cas échéant.	true
`mccmnc`	string	Le MCCMNC auquel cette tarification s'applique pour la route correspondante, le cas échéant. Remplace la tarification au niveau du pays.	true
`cns`	string	Le préfixe de numérotation auquel cette tarification s'applique pour la route correspondante, le cas échéant. Remplace la tarification au niveau du pays et au niveau MCCMNC.	true
`route_type`	string	Le type de route correspondant, c'est-à-dire `HLR`, `MNP`, `NT`.	false
`route_type`	string	Le prix correspondant en EUR.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/balanceprotégé

Ce point de terminaison récupère le solde actuel de votre compte, vous permettant d'automatiser des processus en fonction de votre statut de crédit. Il fonctionne de manière transparente avec les emails de notification de crédit faible que vous pouvez configurer sur votre page de paiements.

Requête Réponse de succès Réponse d'erreur

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

{
    "balance":"1002.90"
}

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`balance`	string	Le solde actuel de votre compte en EUR. Une valeur décimale de type chaîne de caractères.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/pingpublic

Ce point de terminaison envoie une requête ping à l'API, offrant une méthode simple pour tester votre connexion à l'API HLR Lookups.

Requête Réponse de succès Réponse d'erreur

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

{
    "success":true
}

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`success`	boolean	Indique que la requête a été traitée avec succès.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/timepublic

Ce point de terminaison retourne un horodatage Unix représentant l'heure actuelle du serveur HLR Lookups. Utilisez-le pour synchroniser l'horloge de votre serveur lors de la génération de la signature Digest-Auth pour l'authentification, garantissant ainsi que toute divergence entre l'heure de votre serveur et celle du serveur HLR Lookups soit corrigée.

Requête Réponse de succès Réponse d'erreur

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

{
    "time":1525898643
}

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`time`	integer	Horodatage Unix représentant l'heure actuelle du serveur HLR Lookups.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

GET/auth-testprotégé

Ce point de terminaison sert de test initial pour votre implémentation Basic-Auth ou, de préférence, Digest-Auth.

Requête Basic Auth Requête Digest Auth Réponse de succès Réponse d'erreur

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

En-têtes de requête

Clé	Type	Description
`X-Basic`	string	Hash SHA256 de `YOUR_API_KEY:YOUR_API_SECRET`. Incluez le symbole deux-points (:) dans le 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"

En-têtes de requête

Clé	Type	Description
`X-Digest-Key`	string	Votre clé API HLR Lookups
`X-Digest-Signature`	string	Signature Digest-Auth unique (voir authentification)
`X-Digest-Timestamp`	integer	Horodatage Unix actuel (voir également `GET /time`)

{
    "success":true
}

Attributs de la réponse de succès

Nom	Type	Description	Nullable
`success`	boolean	Indique que la requête a été traitée avec succès.	false

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

Paramètres de réponse d'erreur

Nom	Type	Description	Nullable
`errors[]`	string[]	Une liste de chaînes expliquant l'erreur.	false

Remonter

Documentation API héritée

Veuillez noter que l'API héritée est obsolète et sera retirée prochainement. Nous vous recommandons vivement de migrer vers la dernière version dans les meilleurs délais.

Si vous avez implémenté notre API HLR Lookups entre 2013 et début 2020, vous utilisez notre API héritée. Veuillez consulter notre documentation API héritée dans ce cas.

Documentation API héritée

Documentation API

Premiers Pas

Requêtes HLR

Requêtes MNP

Requêtes NT

Routage

Tarification

Outils

Premiers Pas

Utilisation de l'API HLR Lookups

Exemple de Requête

Exemple de Charge Utile

Réponse de succès application/json

Services de Recherche Supplémentaires

Recherches de Portabilité des Numéros Mobiles (MNP)

Recherches de Détection de Type de Numéro (NT)

Kits de Développement Logiciel (SDK)

Outils

Vous n'êtes pas Développeur ?

Authentification

Clé API et Secret API

HTTP Basic Auth

Recommandé : En-tête X-Basic avec SHA256

Requête Basic Auth

En-têtes d'authentification Basic

Exemple de code

Exemple de requête

En-têtes de requête

Construction de la signature

Composants de la signature Digest

Exemples de code

Concepts

API de requête HLR synchrone

API de consultation HLR asynchrone

SDK (Kits de Développement Logiciel)

SDK PHP

SDK NodeJS

SDK Ruby

POST/hlr-lookupprotégé

Charge utile

Paramètres de requête

Attributs de la réponse de succès

Paramètres de réponse d'erreur

POST/hlr-lookupsprotégé

Charge utile

Paramètres de requête

Attributs de la réponse de succès

Paramètres de réponse d'erreur

Traitement des Webhooks

Authentification

Exemple de code

Confirmation de Réception

Charge Utile du Webhook

Attributs de la charge utile du webhook

POST/mnp-lookupprotégé

Charge utile

Paramètres de requête

Attributs de la réponse de succès

Paramètres de réponse d'erreur

POST/mnp-lookupsprotégé

Charge utile

Paramètres de requête

Attributs de la réponse de succès

Paramètres de réponse d'erreur

Traitement des Webhooks

Authentification

Exemple de code

Confirmation de Réception

Charge Utile du Webhook

Attributs de la charge utile du webhook

POST/nt-lookupprotégé

Charge utile

Paramètres de requête

Attributs de la réponse de succès

Paramètres de réponse d'erreur

POST/nt-lookups protégé

Charge utile

Paramètres de requête

Attributs de la réponse de succès

Paramètres de réponse d'erreur