Products

What is Number Lookup & How To Use It For Number Validation

All you need to know about number validation, a step-by-step code tutorial through Number Lookup queries and functionalities.

November 03 2016

The definition of Number Lookup

Number Lookup, also known as HLR (Home Location Register) lookup, is a particular telecommunications service that dynamically contacts a central database (on the operator’s side) that contains details of each mobile phone subscriber authorized to use the GSM core network.

In recent years, number lookup queries have found useful applications in campaigns and programs based on mobile phone numbers. Companies have used them to automatically check validity and status of mobile numbers in their databases, which allowed them to optimize different processes and reduce costs.

IMSI = MCC+MNC+MSIN and has 15 digits

Every phone number contains information that differentiates it from any other phone number in the world. First there is IMSI (International Mobile Subscriber Identity), a fifteen digit number that carries the information about MCC (Mobile country code), MNC (Mobile network code) and MSIN (Mobile Subscription Identification number).

{
  "results": [
    {
      "to": "3859927xxxxx",
      "mccMnc": "21901",
      "imsi": "219019906074188",
      "originalNetwork": {
        "networkName": "T-Mobile HR",
        "networkPrefix": "992",
        "countryName": "Croatia",
        "countryPrefix": "385"
      },
      "ported": false,
      "roaming": false,
      "status": {
        "groupId": 3,
        "groupName": "DELIVERED",
        "id": 5,
        "name": "DELIVERED_TO_HANDSET",
        "description": "Message delivered to handset"
      },
      "error": {
        "groupId": 0,
        "groupName": "OK",
        "id": 0,
        "name": "NO_ERROR",
        "description": "No Error",
        "permanent": false
      }
    }
  ]
}

The first three digits in IMSI are the number’s country code (for Croatia this is 219). The second two numbers are 01, and they identify the network, in this case T-Mobile Croatia. The last ten digits go, they describe the MSIN, a 10-digit unique number that any carrier uses to identify the user’s mobile phone.

Secondly, what Number Lookup helps with is MNP (mobile number portability), i.e. whether a mobile number is ported or not. It’s not unusual that a subscriber of one mobile network operator transfers to another operator but keeps the old number. That’s a common occurrence in almost every country in the world.

Thirdly, Number Lookup also helps you understand if a phone number is in roaming. This can be of crucial importance when you try to protect your clients and prevent fraudulent actions towards their account.

Number Lookup: Sync vs. Async

There are two ways to perform a successful Number Lookup. One is synchronous, performed over HTTP API when a client sends a single or multiple number lookup query. The important thing with this type of Lookup is that with it, if you make multiple number lookups you’ll have to wait until every single Lookup is completed. Sometimes, if there is a list of numbers needed to be checked, it can lead to a queue.

On the other hand, asynchronous Number Lookup, done over a dedicated notifyURL set by a client works differently. With it, you are able to send as many requests as you want, without having to wait for them all to be completed. You’ll get a notification on your notifyURL as soon as we receive it. Depending on the operator, you’ll receive the entire bulk list all at once and sometimes it’s possible to receive every number by itself. This can be rather convenient if you have a large phone number database or multiple databases.

Save response time

The response you receive by looking up numbers with synchronous REST HTTP API is sent after each request, regardless of it being single or bulk. Although the response should be visible in just a couple of seconds, the period between sending a request and receiving a response can be prolonged by various issues. For example, mobile operators have a limited number of requests that can be processed in a fixed time period. This makes the response delivery slower, as you need to wait for the query of the last number to be processed before you can receive a response for the entire Lookup request.

With asynchronous API that speed is improved because you’re able to receive a real time notification. What is different in this case (other than speed) is that this version is a bit more complicated to integrate as the call-back server is required on the client’s side to parse the response with the particular request. Here, security is of the utmost importance - our clients are advised to set up a secure firewall for data protection.

number_lookup_sync_and_async

The most frequent use cases are:

  • checking for active/inactive numbers
  • providing the info about the numbers in roaming
  • checking mobile number portability status
  • finding the optimal route for SMS and Voice messages
  • the type of number (e.g. land-line, machine-to-machine, mobile etc.)

In Infobip we have three main packages available, so you can choose the one that best fits your business:

  • Database Cleaning: Designed for companies with vast number databases, our Database Cleaning package enables identifying unused and inactive numbers.
  • Portability: Developed to resolve number portability issues for various company types, this package enables real-time number portability lookups to optimize message and voice routing. It includes all the features of the Database Cleaning package.
  • Roaming: Primarily created to serve the financial client segment, the package provides roaming information for optimized routing, prevention of ATM frauds and much more.

With the help of Number Lookup you’ll get a better insight into your user database, their behavior, check the phone number’s format to avoid unwanted wrong phone numbers.

After sending promotional messages to your customers and analyzing the delivery reports, sometimes you’ll see the large difference between user data and the number of delivered messages. To prevent unnecessary waste of your money it is advisable to check / clean your database before sending any of your campaigns. Improving the accuracy and cost effectiveness of mobile initiatives is key when you have a large user database, because it saves you more money.

Number Lookup can help you to better understand your customers. See when they are traveling and offer them customized services.

How does Number Lookup work?

The following example shows how you can get Number Lookup information using our API:

JSON
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/json
Accept: application/json
{ 
   "to":["41793026727"]
}

The ‘to’ parameter is a list of all the numbers you want to check.

Here is your result:

JSON
 HTTP/1.1 200 OK
Content-Type: application/json
 
{ 
   "results":[ 
      { 
         "to":"41793026727",
         "mccMnc":"22801",
         "imsi":"228012120181810",
         "originalNetwork":{ 
            "networkPrefix":"79",
            "countryPrefix":"41"
         },
         "ported":false,
         "roaming":false,
         "status":{ 
            "groupId":3,
            "groupName":"DELIVERED",
            "id":5,
            "name":"DELIVERED_TO_HANDSET",
            "description":"Message delivered to handset"
         },
         "error":{ 
            "groupId":0,
            "groupName":"OK",
            "id":0,
            "name":"NO_ERROR",
            "description":"No Error",
            "permanent":false
         }
      }
   ]
}

As we already said, there is a major difference between sync and async types of Number Lookup. We will guide you through both of them, over each line of code. If an API call is synchronous, Number lookup will be done before the app receives the response from an API call. This means that the application code should properly handle waiting for an HTTP response so users don't perceive waiting for Number Lookup response as latency or performance lag inside your app. Making a synchronous API call can be beneficial if there is a code in your app that will only execute properly once the API response is received.

Here is an example of sending a sync multiple phone numbers request:

JSON
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json

{  
   "to":[  
      "41793026727",
      "3859851212"
   ]
}

And the response will be:

JSON
HTTP/1.1 200 OK
Content-Type: application/json

{  
   "bulkId":"f5c4322c-10e7-a41e-5528-34fat43er4134",
   "results":[  
      {  
         "to":"3859851212",
         "mccMnc":"21901",
         "originalNetwork":{  
            "networkPrefix":"98",
            "countryPrefix":"385"
         },
         "ported":false,
         "roaming":false,
         "status":{  
            "groupId":2,
            "groupName":"UNDELIVERABLE",
            "id":9,
            "name":"UNDELIVERABLE_NOT_DELIVERED",
            "description":"Message sent not delivered"
         },
         "error":{  
            "groupId":1,
            "groupName":"HANDSET_ERRORS",
            "id":1,
            "name":"EC_UNKNOWN_SUBSCRIBER",
            "description":"Unknown Subscriber",
            "permanent":true
         }
      },
      {  
         "to":"41793026727",
         "mccMnc":"22801",
         "originalNetwork":{  
            "networkPrefix":"79",
            "countryPrefix":"41"
         },
         "ported":false,
         "roaming":false,
         "status":{  
            "groupId":2,
            "groupName":"UNDELIVERABLE",
            "id":9,
            "name":"UNDELIVERABLE_NOT_DELIVERED",
            "description":"Message sent not delivered"
         },
         "error":{  
            "groupId":1,
            "groupName":"HANDSET_ERRORS",
            "id":27,
            "name":"EC_ABSENT_SUBSCRIBER",
            "description":"Absent Subscriber",
            "permanent":false
         }
      }
   ]
}

For more code examples of a synchronous Number Lookup visit our developer web hub.

Unlike the synchronous calls, asynchronous calls do not wait for the Number Lookup to be done with the entire bulk query before a call response is returned. When a lookup query for any of numbers is done, a "callback" function is executed and Number Lookup information is sent to the notifyUrl you specified in the request.

Here is an example of sending an async multiple phone numbers request:

JSON
POST /number/1/notify HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json

{  
   "to":[  
      "41793026727",
      "12345678",
      "Alphanumeric"
   ],
   "notifyUrl":"http://example.com/notifyUrl",
   "notifyContentType":"application/json"
}

With the notification:

HTTP/1.1 200 OK
Content-Type: application/json
Accept: application/json
{  
   "bulkId":"f5c4322c-10e7-a41e-5528-34fa0b032134",
   "results":[  
      {  
         "to":"41793026727",
         "status":{  
            "groupId":1,
            "groupName":"PENDING",
            "id":7,
            "name":"PENDING_ENROUTE",
            "description":"Message sent to next instance"
         },
         "messageId":"c2598a78-ba88-423f-8ac3-5dac4af816cf"
      },
      {  
         "to":"12345678",
         "status":{  
            "groupId":5,
            "groupName":"REJECTED",
            "id":14,
            "name":"REJECTED_DESTINATION",
            "description":"By Destination",
            "action":"Remove destination from blacklist"
         },
         "messageId":"a70437bc-872c-5462-837a-4ede899af3bf"
      },
      {  
         "to":"Alphanumeric",
         "status":{  
            "groupId":5,
            "groupName":"REJECTED",
            "id":52,
            "name":"REJECTED_DESTINATION",
            "description":"Invalid destination address.",
            "action":"Check to parameter."
         }
      }
   ]
}

Note that in this example you can receive just one notification but also you can receive a notification for each number individually.

Your mobile subscribers often change numbers, go into roaming and change providers while retaining their original phone number. Knowing which mobile numbers are in use and available, or which network your client is currently using can greatly improve accuracy and cost effectiveness for many types of businesses. Hopefully, this blog helped you maintain a cleaner database and helped you reach your users.

Learn more about Number Lookup.

Start validating numbers today