API HLR de CaptainVerify

API HLR

Avec l'API de CaptainVerify, vous pouvez intégrer la vérification HLR Lookup dans vos propres applications. Vous pouvez aussi jeter un œil à la documentation HLR.

Clé API

Un compte est nécessaire pour générer la clé pour l'API, c'est ce qui vous donnera accès au service.

La requête

Pour faire une demande à l'API, appelez simplement le protocole GET à cette URL:

https://api.captainverify.com/verify?phone={PHONE_NUMBER}&apikey=XXXXXXXXXXXXXXXXXXXX

Remplacez {PHONE_NUMBER} par le numéro mobile à vérifier (au format international : +336...)

Limites de l'API

L'API est limitée à un maximum de 2 connexions simultanées et 50 vérifications par minute. Lorsque vous intégrez l'API, assurez-vous que votre application ne dépasse pas cette limite.

La réponse

Une table json sera renvoyée avec ces variables:

Variables	Valeur possible
status	true, false. Le statut de la requete.
credits	89 Crédits disponibles sur votre compte.
message	default : null Lorsque le status est faux, un message d'erreur sera envoyé.
requested_number	33600000000 Le numéro mobile à interroger.
formatted_number	+33600000000 Le numéro mobile format international.
network	Free Mobile Le nom du réseau.
original_network	Orange Le nom d'origine du réseau.
roaming	true, false L'état d'itinérance actuel.
ported	true, false Si l'utilisateur a changé d'opérateur avec le même numéro.
country	France Le nom complet du pays pour le numéro demandé.
country_prefix	33 Le préfixe numérique du pays du numéro.
details	DELIVERED_TO_HANDSET, UNDELIVERABLE_NOT_DELIVERED DELIVERED_TO_HANDSET : La vérification HLR a été traité (numéro attribué). UNDELIVERABLE_NOT_DELIVERED: La vérification HLR n'a pas été jusqu'au bout (numéro non attribué).
result	Le statut du numéro : valid, invalid, unknow Si tous vos crédits ont été épuisés, le statut inconnu sera toujours retourné, pour ne pas bloquer votre application.

Pourquoi intégrer une API HLR ?

Un fichier de numéros mobiles vieillit vite. Des lignes sont résiliées, des numéros changent d'opérateur, d'autres comportent une faute de saisie et n'ont jamais existé. Chaque SMS envoyé vers un numéro invalide est facturé, mais il n'arrive jamais. Sur une campagne de plusieurs milliers de messages, ces envois perdus pèsent directement sur le budget sans produire le moindre retour.

Le problème dépasse le SMS. En prospection téléphonique, un fichier pollué par des numéros résiliés fait perdre du temps aux équipes : chaque appel vers une ligne morte est un appel qui n'aboutira pas. Les statistiques de campagne deviennent illisibles, la délivrabilité SMS se dégrade et il devient impossible de distinguer un message ignoré d'un message jamais délivré.

Une API HLR traite le problème à la source. Le HLR (Home Location Register) est le registre des opérateurs qui recense l'état des lignes mobiles. En interrogeant le réseau de l'opérateur en temps réel, l'API confirme qu'une ligne est active avant que vous ne la contactiez. Vous cessez d'envoyer à l'aveugle et vous ne payez plus pour joindre des numéros qui n'existent plus.

Cas d'usage de l'API HLR

Nettoyage d'un fichier mobile avant campagne SMS

Avant un envoi en masse, passez chaque numéro par l'API. Les lignes actives sont conservées, les numéros résiliés ou invalides sont écartés du fichier. Vous ne payez que des SMS qui ont une chance réelle d'être délivrés, et vos taux de campagne reflètent la qualité de votre message plutôt que l'usure de votre base.

Filtrage avant prospection téléphonique

Un centre d'appels perd de l'argent à chaque numéro mort composé. En vérifiant le statut des lignes en amont, vous ne transmettez aux équipes que des numéros actifs. Les commerciaux passent leur temps à parler à des prospects, pas à écouter des messages d'erreur opérateur. Le coût par contact utile baisse mécaniquement.

Détection des numéros résiliés dans un CRM

Les fiches contact d'un CRM se dégradent en silence. Une vérification HLR périodique identifie les lignes résiliées et permet de marquer ces fiches, de déclencher une mise à jour ou de basculer vers un autre canal de contact. Votre base reste exploitable au lieu d'accumuler des numéros morts qui faussent tous vos indicateurs.

Identification de l'opérateur réel malgré la portabilité

Un numéro porté conserve son préfixe d'origine mais dépend désormais d'un autre opérateur. La réponse de l'API distingue le réseau actuel (network) du réseau d'origine (original_network). Vous savez quel opérateur gère réellement la ligne, une information précieuse pour le routage de vos SMS ou l'analyse de la composition de votre fichier.

Questions fréquentes sur l'API HLR

Que vérifie exactement l'API HLR ?

L'API interroge l'opérateur pour connaître le statut de la ligne mobile. La réponse JSON contient le statut de la requête, le numéro formaté en international, le réseau actuel et le réseau d'origine. La comparaison de ces deux derniers champs révèle si le numéro a été porté vers un autre opérateur.

L'API fonctionne-t-elle en temps réel ?

Oui. Chaque requête déclenche une interrogation du réseau de l'opérateur au moment où vous l'envoyez. Deux limites documentées encadrent l'usage : 2 connexions simultanées au maximum et 50 vérifications par minute. Pour traiter de gros volumes, il suffit de cadencer vos appels dans le respect de ces seuils.

Combien ça coûte ?

La facturation fonctionne par crédits, et chaque réponse de l'API comporte un champ credits qui vous permet de suivre votre consommation directement depuis vos appels. Les tarifs détaillés des vérifications HLR sont disponibles sur la page HLR Lookup.