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

JSON

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

{  
   "to":["41793026727"]
}

					{  
   "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:

JSON
XML

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:

JSON
XML

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:

JSON
XML

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