Number Lookup over API
Here's how to use Number Lookup using API.
Request example:
{
"to": [
"41793026727"
]
}
The to parameter is a list of all the numbers you want to check.
Response example:
{
"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
}
}
]
}
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, visit Number Lookup Synchronous Request (opens in a new tab).
Sync vs. Async
Learn about the difference between synchronous and asynchronous Number Lookup.
Number Lookup provides information about phone numbers in your database. There are two ways of getting that information:
- Sync
- Async
If an API call is synchronous, it means that Number Lookup will be done before your application receives a response from the API call. In turn, this means the application code should properly handle waiting for the HTTP response so thet users don’t perceive waiting for 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.
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:
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.
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
You’ve sent promotional messages to your customers, then analyzed the delivery reports and found out that your phone number database has a lot of invalid numbers. You may consider cleaning it up with our Number Lookup solution.
To clean up your database, you need to have our Database Cleaning package and perform Number Lookup with an HTTP POST request:
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:
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 learn whether a phone number is valid or not. Here is the list of available Number Lookup parameters per package (opens in a new tab) and also the list of available statuses (opens in a new tab).
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.