CaptainVerify HLR Lookup API

HLR Lookup API

With the CaptainVerify API, you can integrate the HLR lookup verification in your own applications. You can also take a look at HLR documentation.

API key

An account is necessary to generate the key for the API, this is what will give you access to the service.

The request

To make a request to the API, simply call the GET protocol to this URL:

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

Replace {PHONE_NUMBER} with the mobile number to check (international format : +447...)

API limits

The API is limited to a maximum of 2 simultaneous connections and 50 checks per minute. When you integrate the API, make sure your application does not exceed this limit.

The answer

A JSON table will be returned with these variables:

Variables	Possible value
status	true, false. The status of the request.
credits	89 Credits available to your account.
message	default : null When the status is false, an error message will be sent.
requested_number	447000000000 The mobile number to question.
formatted_number	+447000000000 International mobile format number.
network	T-MOBILE UK Network name.
original_network	3 The original name of the network.
roaming	true, false The current itinerant state.
ported	true, false If the user has changed operator with the same number.
country	UNITED KINGDOM The full name of the country for the requested number.
country_prefix	44 The digital prefix of the country of the number.
details	DELIVERED_TO_HANDSET, UNDELIVERABLE_NOT_DELIVERED DELIVERED_TO_HANDSET : HLR verification has been processed (assigned number). UNDELIVERABLE_NOT_DELIVERED: HLR verification has not been to the end (number not attributed).
result	The status of the number: Valid, Invalid, Unknow If all your credits have been exhausted, the unknown status will always be returned, so as not to block your application.

Why integrate an HLR lookup API?

A mobile number file ages fast. Lines get cancelled, numbers move to another carrier, others contain a typo and never existed at all. Every SMS sent to an invalid number is billed, yet it never arrives. Across a campaign of several thousand messages, these wasted sends weigh directly on the budget without producing the slightest return.

The problem goes beyond SMS. In phone prospecting, a file polluted with cancelled numbers wastes your teams' time: every call to a dead line is a call that will never connect. Campaign statistics become unreadable, SMS deliverability degrades and it becomes impossible to tell an ignored message from a message that was never delivered.

An HLR lookup API tackles the problem at the source. The HLR (Home Location Register) is the carriers' registry that records the status of mobile lines. By querying the carrier's network in real time, the API confirms that a line is active before you contact it. You stop sending blind and you no longer pay to reach numbers that no longer exist.

HLR lookup API use cases

Cleaning a mobile file before an SMS campaign

Before a bulk send, run every number through the API. Active lines are kept, cancelled or invalid numbers are removed from the file. You only pay for SMS messages that have a real chance of being delivered, and your campaign rates reflect the quality of your message rather than the decay of your database.

Filtering before phone prospecting

A call center loses money on every dead number dialed. By checking line status upstream, you only pass active numbers on to your teams. Sales reps spend their time talking to prospects, not listening to carrier error messages. The cost per useful contact drops mechanically.

Detecting cancelled numbers in a CRM

CRM contact records degrade silently. A periodic HLR check identifies cancelled lines and lets you flag those records, trigger an update or switch to another contact channel. Your database stays usable instead of accumulating dead numbers that distort all your metrics.

Identifying the real carrier despite number portability

A ported number keeps its original prefix but now depends on another carrier. The API response distinguishes the current network (network) from the original network (original_network). You know which carrier actually manages the line, valuable information for routing your SMS messages or analyzing the composition of your file.

Frequently asked questions about the HLR lookup API

What exactly does the HLR lookup API check?

The API queries the carrier to determine the status of the mobile line. The JSON response contains the request status, the number formatted in international format, the current network and the original network. Comparing these last two fields reveals whether the number has been ported to another carrier.

Does the API work in real time?

Yes. Each request triggers a query to the carrier's network at the moment you send it. Two documented limits govern usage: a maximum of 2 simultaneous connections and 50 checks per minute. To process large volumes, simply pace your calls within these thresholds.

How much does it cost?

Billing works with credits, and each API response includes a credits field that lets you track your consumption directly from your calls. Detailed pricing for HLR checks is available on the HLR Lookup page.