Synchronous request
This method gives you the ability to make a synchronous Number Lookup request over HTTP. Number Lookup response is returned immediately, eliminating the need for the call back server.
Resource
https://api.infobip.com/number/1/query
Unlike the asynchronous version of Number Lookup, this endpoint is intended to be used to check smaller amounts of phone numbers and does not support batch processing. It is more convenient, and can be used in scenarios like validating individual phone numbers collected from the user interface. Note that this API endpoint may incur larger latency then the rest of the API.
Parameters
Property name | Type | Description |
---|---|---|
to* | array_string | Array of Number Lookup destination addresses. Maximum supported number of destination addresses is 1000 per request. If the Number Lookup is requested for one phone number, a single String is supported instead of an Array. Destination addresses must be in international format (Example: 41793026727). |
Request Example
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
"to":["41793026727"]
}
Response
{
"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
}
}
]
}
{
"requestError": {
"serviceException": {
"messageId": "BAD_REQUEST",
"text": "[to : Number of destinations is limited to 1000. For larger requests use /number/1/notify API endpoint.]"
}
}
}
Response format
If successful, the response header HTTP status code will be 200 OK
and include Number Lookup information in the response body.
If you try to send a Number Lookup without authorization, you will get a response with the HTTP status code 401 Unauthorized
.
If your request contains more than 1000 destination addresses, API will return the status code 400 Bad Request
.
NCResponse
Parameter | Type | Description |
---|---|---|
bulkId | String | The ID that uniquely identifies the request. Bulk ID will be received only when you send a Number Lookup to more than one destination address. |
results | NCResponseDetails | Array of Number Lookup results, one per every phone number. |
NCResponseDetails
Parameter | Type | Description |
---|---|---|
to | String | The Number Lookup destination address. |
mccMnc | String | Mobile country code and mobile network code concatenated. MccMnc will start with the MCC, and it will always have three digits, followed by the MNC (length of the MNC depends on the value of the MCC, and it can be two or three). |
imsi | String | International Mobile Subscriber Identity, used to uniquely identify the user of a mobile network. |
originalNetwork | Network | Information about the original network. |
ported | Boolean | Tells if the phone number is ported. |
portedNetwork | Network | Information about the ported network. |
roaming | Boolean | Informs if the phone number is in roaming. |
roamingNetwork | Network | Information about the roaming network. |
servingMSC | String | Serving mobile switching center. |
status | Status | Indicates whether the Number Lookup query was successfully executed, not executed or any other possible status. |
error | Error | Indicates whether the error occurred during the query execution. |
Network
Parameter | Type | Description |
---|---|---|
networkName | String | Network name. |
networkPrefix | String | Network prefix. |
countryName | String | Country name. |
countryPrefix | String | Country prefix. |
Status
Parameter | Type | Description |
---|---|---|
groupId | int | Status group ID. |
groupName | String | Status group name. |
id | int | Status ID. |
name | String | Status name. |
description | String | Human-readable description of the status. |
action | String | Action that should be taken to eliminate the error. |
Error
Parameter | Type | Description |
---|---|---|
groupId | int | Error group ID. |
groupName | String | Error group name. |
id | int | Error ID. |
name | String | Error name. |
description | String | Human-readable description of the error. |
permanent | boolean | Tells if the error is permanent. |
Information:
Various Number Lookup packages are available. Depending on your package, some information may not be accessible. For a package change, contact your Account Manager.
Additional examples
Number Lookup - Single phone number
Request:
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
"to":["41793026727"]
}
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/xml
Accept: application/xml
<request>
<to>41793026727</to>
</request>
curl -X POST \
-H "Content-Type: application/json" \
-H 'Accept: application/json' \
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
-d '{
"to":["41793026727"]
}' https://api.infobip.com/number/1/query
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "http://api.infobip.com/number/1/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"to\":[\"41793026727\"]}",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
require 'uri'
require 'net/http'
url = URI("https://api.infobip.com/number/1/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"to\":[\"41793026727\"]}"
response = http.request(request)
puts response.read_body
import http.client
conn = http.client.HTTPSConnection("api.infobip.com")
payload = "{\"to\":[\"41793026727\"]}"
headers = {
'authorization': "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
'accept': "application/json",
'content-type': "application/json"
}
conn.request("POST", "/number/1/query", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.infobip.com/number/1/query")
.header("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
.header("accept", "application/json")
.header("content-type", "application/json")
.body("{\"to\":[\"41793026727\"]}")
.asString();
var client = new RestClient("https://api.infobip.com/number/1/query");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
request.AddParameter("application/json", "{\"to\":[\"41793026727\"]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
var data = JSON.stringify({
"to": [
"41793026727"
]
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.infobip.com/number/1/query");
xhr.setRequestHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
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
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/xml
<ncResponse>
<results>
<result>
<to>41793026727</to>
<mccMnc>22801</mccMnc>
<originalNetwork>
<networkPrefix>79</networkPrefix>
<countryPrefix>41</countryPrefix>
</originalNetwork>
<ported>false</ported>
<roaming>false</roaming>
<status>
<groupId>2</groupId>
<groupName>UNDELIVERABLE</groupName>
<id>9</id>
<name>UNDELIVERABLE_NOT_DELIVERED</name>
<description>Message sent not delivered</description>
</status>
<error>
<groupId>1</groupId>
<groupName>HANDSET_ERRORS</groupName>
<id>27</id>
<name>EC_ABSENT_SUBSCRIBER</name>
<description>Absent Subscriber</description>
<permanent>false</permanent>
</error>
</result>
</results>
</ncResponse>
Number Lookup - Multiple phone numbers
Request:
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
"to":[
"41793026727",
"3859851212"
]
}
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/xml
Accept: application/xml
<request>
<to>
<to>41793026727</to>
<to>3859851212</to>
</to>
</request>
curl -X POST
-H "Content-Type: application/json"
-H 'Accept: application/json'
-H "Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ="
-d '{
"to":[
"41793026727",
"3859851212"
]
}' https://api.infobip.com/number/1/query
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "http://api.infobip.com/number/1/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"to\":[\"41793026727\",\"3859851212\"]}",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
require 'uri'
require 'net/http'
url = URI("https://api.infobip.com/number/1/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"to\":[\"41793026727\", \"3859851212\"]}"
response = http.request(request)
puts response.read_body
import http.client
conn = http.client.HTTPSConnection("api.infobip.com")
payload = "{\"to\":[\"41793026727\", \"3859851212\"]}"
headers = {
'authorization': "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
'accept': "application/json",
'content-type': "application/json"
}
conn.request("POST", "/number/1/query", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.infobip.com/number/1/query")
.header("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
.header("accept", "application/json")
.header("content-type", "application/json")
.body("{\"to\":[\"41793026727\", \"3859851212\"]}")
.asString();
var client = new RestClient("https://api.infobip.com/number/1/query");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
request.AddParameter("application/json", "{\"to\":[\"41793026727\", \"3859851212\"]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
var data = JSON.stringify({
"to": [
"41793026727",
"3859851212"
]
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.infobip.com/number/1/query");
xhr.setRequestHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
Response:
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
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/xml
<ncResponse>
<bulkId>f5c4322c-10e7-a41e-5528-34fat43er4134</bulkId>
<results>
<result>
<to>41793026727</to>
<mccMnc>22801</mccMnc>
<originalNetwork>
<networkPrefix>79</networkPrefix>
<countryPrefix>41</countryPrefix>
</originalNetwork>
<ported>false</ported>
<roaming>false</roaming>
<status>
<groupId>2</groupId>
<groupName>UNDELIVERABLE</groupName>
<id>9</id>
<name>UNDELIVERABLE_NOT_DELIVERED</name>
<description>Message sent not delivered</description>
</status>
<error>
<groupId>1</groupId>
<groupName>HANDSET_ERRORS</groupName>
<id>27</id>
<name>EC_ABSENT_SUBSCRIBER</name>
<description>Absent Subscriber</description>
<permanent>false</permanent>
</error>
</result>
<result>
<to>3859851212</to>
<mccMnc>21901</mccMnc>
<originalNetwork>
<networkPrefix>98</networkPrefix>
<countryPrefix>385</countryPrefix>
</originalNetwork>
<ported>false</ported>
<roaming>false</roaming>
<status>
<groupId>2</groupId>
<groupName>UNDELIVERABLE</groupName>
<id>9</id>
<name>UNDELIVERABLE_NOT_DELIVERED</name>
<description>Message sent not delivered</description>
</status>
<error>
<groupId>1</groupId>
<groupName>HANDSET_ERRORS</groupName>
<id>1</id>
<name>EC_UNKNOWN_SUBSCRIBER</name>
<description>Unknown Subscriber</description>
<permanent>true</permanent>
</error>
</result>
</results>
</ncResponse>
Number Lookup - Ported phone number
Request:
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Content-Type: application/json
Accept: application/json
{
"to":["44788740087"]
}
POST /number/1/query HTTP/1.1
Host: api.infobip.com
Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=
Content-Type: application/xml
Accept: application/xml
<request>
<to>44788740087</to>
</request>
curl -X POST \
-H "Content-Type: application/json" \
-H 'Accept: application/json' \
-H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ=" \
-d '{
"to":["44788740087"]
}' https://api.infobip.com/number/1/query
<?php
$curl = curl_init();
curl_setopt_array($curl, array(
CURLOPT_URL => "http://api.infobip.com/number/1/query",
CURLOPT_RETURNTRANSFER => true,
CURLOPT_ENCODING => "",
CURLOPT_MAXREDIRS => 10,
CURLOPT_TIMEOUT => 30,
CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
CURLOPT_CUSTOMREQUEST => "POST",
CURLOPT_POSTFIELDS => "{\"to\":[\"44788740087\"]}",
CURLOPT_HTTPHEADER => array(
"accept: application/json",
"authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
"content-type: application/json"
),
));
$response = curl_exec($curl);
$err = curl_error($curl);
curl_close($curl);
if ($err) {
echo "cURL Error #:" . $err;
} else {
echo $response;
}
require 'uri'
require 'net/http'
url = URI("https://api.infobip.com/number/1/query")
http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true
http.verify_mode = OpenSSL::SSL::VERIFY_NONE
request = Net::HTTP::Post.new(url)
request["authorization"] = 'Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ=='
request["accept"] = 'application/json'
request["content-type"] = 'application/json'
request.body = "{\"to\":[\"44788740087\"]}"
response = http.request(request)
puts response.read_body
import http.client
conn = http.client.HTTPSConnection("api.infobip.com")
payload = "{\"to\":[\"44788740087\"]}"
headers = {
'authorization': "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==",
'accept': "application/json",
'content-type': "application/json"
}
conn.request("POST", "/number/1/query", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
HttpResponse<String> response = Unirest.post("https://api.infobip.com/number/1/query")
.header("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==")
.header("accept", "application/json")
.header("content-type", "application/json")
.body("{\"to\":[\"44788740087\"]}")
.asString();
var client = new RestClient("https://api.infobip.com/number/1/query");
var request = new RestRequest(Method.POST);
request.AddHeader("content-type", "application/json");
request.AddHeader("accept", "application/json");
request.AddHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
request.AddParameter("application/json", "{\"to\":[\"44788740087\"]}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
var data = JSON.stringify({
"to": [
"44788740087"
]
});
var xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.infobip.com/number/1/query");
xhr.setRequestHeader("authorization", "Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==");
xhr.setRequestHeader("accept", "application/json");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
Response:
HTTP/1.1 200 OK
Content-Type: application/json
{
"results": [
{
"to": "44788740087",
"mccMnc": "23410",
"imsi": "23410988740087",
"originalNetwork": {
"networkName": "Vodafone UK",
"networkPrefix": "78874",
"countryName": "United Kingdom",
"countryPrefix": "44"
},
"ported": true,
"portedNetwork": {
"networkName": "O2 (Telefonica UK Ltd)",
"networkPrefix": "76020",
"countryName": "United Kingdom",
"countryPrefix": "44"
},
"roaming": false,
"servingMSC": "447802",
"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
}
}
]
}
HTTP/1.1 200 OK
Content-Type: application/xml
<ncResponse>
<results>
<result>
<to>44788740087</to>
<mccMnc>23410</mccMnc>
<imsi>23410988740087</imsi>
<originalNetwork>
<networkName>Vodafone UK</networkName>
<networkPrefix>78874</networkPrefix>
<countryName>United Kingdom</countryName>
<countryPrefix>44</countryPrefix>
</originalNetwork>
<ported>true</ported>
<portedNetwork>
<networkName>O2 (Telefonica UK Ltd)</networkName>
<networkPrefix>76020</networkPrefix>
<countryName>United Kingdom</countryName>
<countryPrefix>44</countryPrefix>
</portedNetwork>
<roaming>false</roaming>
<servingMSC>447802</servingMSC>
<status>
<groupId>3</groupId>
<groupName>DELIVERED</groupName>
<id>5</id>
<name>DELIVERED_TO_HANDSET</name>
<description>Message delivered to handset</description>
</status>
<error>
<groupId>0</groupId>
<groupName>OK</groupName>
<id>0</id>
<name>NO_ERROR</name>
<description>No Error</description>
<permanent>false</permanent>
</error>
</result>
</results>
</ncResponse>