Verify phone numbers — a developer’s guide

Mobile phone numbers are increasingly used by companies, apps and websites to verify the user’s identity or to provide an extra layer of security when logging a user into his account. As a developer, there are several ways to verify phone numbers. It all depends on your goal.

Lookup API

Our new Lookup API is one of the most basic ways to verify phone numbers and it’s also the cheapest one; it’s absolutely free to use. This API checks if a valid number is provided, in the most basic sense. The only input that is needed is an international number or a national number with the country code. The lookup API will tell you if the number has an unknown format (HTTP status 400) or if it is correct (200, \o/). When the number is correct, it will provide you with a JSON object with additional information; country-code, country-prefix, type and the phone number formatted in four different ways. Examples of reasons why you would use our Lookup API are:

• Provide basic validation for phone numbers that users submits in a web form.
• Cleaning up a phone number list or database.
• Check if you should send a user an SMS (type: Mobile) or send a Text-to-Speech message (type: Landline & VoIP).

Example request:

curl https://rest.messagebird.com/lookup/31612345678 \
-H ‘Authorization: AccessKey test_gshdoso2eEG6ovbc8M79w0QyM’

Example response:

What do you get? Basic validation, phone type and formatting information
How much does it cost? Nothing, it’s free!
How can you implement it? Check out our developers page and our ready-to-go libraries

HLR API

Within the lookup API, we provide an extra service called, HLR (Home Location Register). With an HLR request, you can check if the phone number really exists on the worldwide phone network (also called SS7 or Signalling no. 7 protocol). Just as the basic lookup, the only information that is needed is the phone number that you want to check. When you submit an HLR request at the API, we will do a current request on the worldwide telephone network (SRI request between MSC and the HLR) to check the status of the number. After you have submitted the request we will provide you with the collected information through an async call or you can just do a GET instead of a POST on the resource object after a couple of seconds (tops). The HLR will provide you the following information:

• Status (active, absent or number unknown)
• Provider (MCCMNC)
• Country code + full country name
• The Mobile Switching Center (MSC) the mobile is on
• Ported status
• Roaming status

In some countries you also get:

• IMSI
• Location information

So HLR gives you the option to check if a valid phone number is being provided not only in terms of format, but also if it’s currently active or absent on the telephone network and can be used to filter out all expired phone numbers in a list.

Example request (a GET after a POST):

curl https://rest.messagebird.com/lookup/31635778012/hlr \
-H ‘Authorization: AccessKey test_gshdoso2eEG6ovbc8M79w0QyM’

Example response:

What do you get? Extended validation, plus network information
How much does it cost? € 0,005 per request
How can I implement it? Check out our developers page and our ready-to-go libraries

Verify API

The last API that I want to tell you about is our verify API. With the verify API you can check if the user has access to the phone number that he entered to identify himself. Our verify API is regularly used for two-factor authentication or to log in a website or app. This is done by sending a one-time password code to the provided phone number and making sure that the user has received the SMS or voice message by asking him to submit the received one-time password code on your website or into your app. Note that we save the token hashed on our platform, so no one has access to the token created, except the receiver of the message.

Once again, the only thing you need is the phone number of the user. Verifying phone numbers with a one-time-password is somewhat more complex than doing a lookup or HLR request, but should be straightforward none the less. You as a developer can configure various parameters. For example, you can set an originator, choose the type of message (SMS, Flash SMS, Text-to-Speech), form the template of the message and a lot more. The phone number is the only required parameter. When a new verification process through our API is being requested (for instance a user wants to login to his account) the response from our platform is a JSON object with a unique id (which you will need later on). Simultaneously we will send a one-time-password to the user’s phone number, that you can obtain from your user by asking him to enter this one-time-password in an input field. By sending us this one-time-password, accompanied by the unique id, you’ll receive a response from our platform telling you if the one-time-password is correct. Easy does it.

Example request:

curl -X POST https://rest.messagebird.com/verify \
-H ‘Authorization: AccessKey test_gshdoso2eEG6ovbc79w0QyM’ \
-d “recipient=31612345678” \
-d “originator=MessageBird”

Example response

What do you get? Validation through identity check
How much does it cost? The price of an SMS or voice message
How can I implement it? Check out our developers page and our ready-to-go libraries

Summary

There are several ways to verify phone numbers, depending on your goal. You can go all-out with our verify API or just keep it simple with our lookup API. For all mentioned APIs we provided ready-to-go libraries (PHP, Ruby, Go, C#, Python, Java, NodeJS) and examples to use them.

Got questions about this post, our products or APIs? Hit me up with a comment here or send me a tweet!