Number Lookup over API

To use number lookup over API, use the Number Lookup (opens in a new tab) API.

The following shows examples of the request and response.

Request example:

json

 
    {
      "to": [
        "41793026727"
      ]
    }

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

Response example:

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

INFORMATION

Depending on your package, some information may not be accessible. For a package change, contact your Account Manager.

For more information about this method and receiving a Number Lookup result on your Notify URL, see Number Lookup Synchronous Request (opens in a new tab).

Sync versus Async

Number Lookup provides information about phone numbers in your database. There are two ways of getting that information:

Synchronous
Asynchronous

Synchronous API calls ensure that Number Lookup occurs before your application receives a response from the API call. This means that the application code can handle the time for the HTTP response so that users do not perceive the wait for the NC lookup response as latency or performance lag inside your app.

Making a synchronous API call can be beneficial if there is code in your app that will only execute properly once the API response is received.

json

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

The Number Lookup result will be received directly in the response:

json

 
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {  
       "results":[  
          {  
             "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
             }
          }
       ]
    }

Asynchronous calls do not wait for Number Lookup to be done before the API call response is returned. When Number Lookup is done, a callback function is executed and Number Lookup information is sent to the notifyUrl you specified in the request.

json

 
    POST /number/1/notify HTTP/1.1
    Host: api.infobip.com
    Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
    Content-Type: application/json
    
    {  
       "to":[  
          "41793026727",
          "41793026728",
          "41793026729"
       ],
       "notifyUrl":"http://example.com/notifyUrl",
       "notifyContentType":"application/json"
    }

Database cleaning

If you have sent promotional messages to your customers, then analyzed the delivery reports, you may then find out that your phone number database has a lot of invalid numbers. You can the clean up your phone number database with Number Lookup.

To clean up your database, you need to have the Database Cleaning package and perform Number Lookup with an HTTP POST request:

json

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

In this example we used only one phone number to make it easier to follow. Depending on the package, the response will be something like this:

json

 
    HTTP/1.1 200 OK
    Content-Type: application/json
    
    {  
       "results":[  
          {  
             "to":"41793026834",
             "mccMnc":"22801",
             "imsi":"228012123477789",
             "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
             }
          }
       ]
    }

From the information you will receive in the Number Lookup response, you can discover whether a phone number is valid or not.

See Number Lookup (opens in a new tab) for a list of available parameters per package, and the list of available statuses.

For example, 30 phone numbers are invalid and 70 are valid, so you decide to remove the 30 invalid ones from your database. This will save you up to 30% of SMS sending costs and you can invite more active subscribers with the same budget.

Number Lookup over Broadcast