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>
Next: Asynchronous request