To get the current number of HLR lookups performed on your account to date, please POST your query to the following URL:
http(s)://api.onesixty.co.uk/rest/v2/hlr/count
| Parameters | Type | Information |
| username (required) |
String | Your OneSixty username. |
| api_key (required) |
String | Your API key. This is different from your password. |
The response format is currently JSON. You will always receive an array in which the first element is the number of HLR lookups charged to date; the second element is the number of cached HLR lookups we have used according to your expiry settings and the third element is the number of HLR credits remaining. You will always receive an array with 3 elements even if an error has occurred.
Here are some example responses (the second one is an example of an error):
[9000,999,1]
[0,0,0]
In order to perform a HLR lookup, you must POST your query to the following URL:
http(s)://api.onesixty.co.uk/rest/v2/hlr
For batch HLR lookups, you must POST your query to the following URL:
http(s)://api2.onesixty.co.uk/rest/v2/hlr
| Parameters | Type | Information |
| username (required) |
String | Your OneSixty username. |
| api_key (required) |
String | Your API key. This is different from your password. |
| msisdn (required) |
String or Array |
The mobile number you wish to perform a lookup on. An international format is required. Do not use the plus sign (+). For example: 44712345678 For batch lookups, please post an array of MSISDNs (up to 1,000). |
The response format is currently JSON. You will always receive an object in which the first value is either integer 0 (fail) or integer 1 (success). The second value is a string message which can be useful for debugging. A third value will be present if the lookup was charged for. The third value is a string submission reference. Here are some sample responses:
{
"0": 0,
"1": "Please check the MSISDN format."
}
{
"0": 0,
"1": "There was a problem obtaining a HLR result, maybe because the handset is switched off or is in a low signal area.",
"2": "21dd76ed37925355bba9df0c92139b5a2e8357dc",
"3": "447712345678"
}
{
"0": 1,
"1": "The specified MSISDN is active.",
"2": "95a84e9649f755c5f3afdd28c662db17dba68ffe",
"3": "447826123456",
"4": 1,
"5": "234159076921451",
"6": "23415",
"original": {
"country_name": "United Kingdom",
"country_prefix": "44",
"network_name": "Vodafone Ltd",
"network_prefix": "7826"
}
}
{
"0": 1,
"1": "Your HLR request has been submitted successfully.",
"2": "fe71702ce65aa26cf49490f3634174dd74f990c5",
"3": 2,
"4": 2,
"5": {
"0": {
"0": 1,
"1": "The specified MSISDN is active.",
"2": "29986a95d48d71de062689d5c8e0dc074e8b77a7",
"3": "447885123456",
"4": 1,
"5": "234109163504859",
"6": "23410",
"original": {
"country_name": "United Kingdom",
"country_prefix": "44",
"network_name": "O2 (Telefonica O2 (UK) Limited)",
"network_prefix": "7885"
}
},
"1": {
"0": 1,
"1": "The specified MSISDN is active.",
"2": "5d96d424a2dbf177dfcf7f61809b3fc7caad4fea",
"3": "447590123456",
"4": 1,
"5": "234103223402610",
"6": "23410",
"original": {
"country_name": "United Kingdom",
"country_prefix": "44",
"network_name": "O2 (Telefonica O2 (UK) Limited)",
"network_prefix": "759"
}
}
}
}
The first sample response was not charged for because of a user error (the MSISDN was in an invalid format). The second sample response was charged for but the required data could not be gathered (due to low signal, etc). Because the lookup was performed, it must be charged for.
The third sample response was successful because the required data was returned. You will see a fifth value here which is either integer 0 (MSISDN is inactive) or integer 1 (MSISDN is active). If the MSISDN is active, the sixth value will be a string IMSI and the seventh value will be a string MCCMNC.
You can also expect to receive up to 3 more objects: original, ported, roaming
You will always receive the original object but the ported object will only be present if an MSISDN has been ported. The same goes for the roaming object - it will only be present if the MSISDN is currently roaming.
For example, you may receive something like the following:
{
"0": 1,
"1": "The specified MSISDN is active.",
"2": "5b7dd16fe4750560ea07480a23fc659c96223260",
"3": "447901123456",
"4": 1,
"5": "234103223366312",
"6": "23410",
"original": {
"country_name": "United Kingdom",
"country_prefix": "44",
"network_name": "Vodafone Ltd",
"network_prefix": "7901"
},
"ported": {
"country_name": "United Kingdom",
"country_prefix": "44",
"network_name": "O2 (Telefonica O2 (UK) Limited)",
"network_prefix": "7732"
}
}
All 3 objects will contain the same data: Country Name, Country Prefix, Network Name & Network Prefix
The fourth sample is an example batch response. The fourth element is the number of fresh HLR lookups that were performed. These results will be sent via HTTP POST to your URL shortly. The fifth element is the number of cached results we have available which are returned in the fifth element. The fifth element will only exist if there are one or more cached results to return. If that is the case, there will be multiple HLR objects like the third sample above.
Receiving HLR results via HTTP POST
Every minute we will attempt to send you new HLR results. You will receive a single parameter named JSON to your URL. It will simply contain a number of objects within an object. For example:
{
"0": {
"0": 1,
"1": "The specified MSISDN is active.",
"2": "d9a33b884269fee325733b9f3e915250e7ef890f",
"3": "447584123456",
"4": 1,
"5": "234159408702479",
"6": "23415",
"original": {
"country_name": "United Kingdom",
"country_prefix": "44",
"network_name": "Vodafone Ltd",
"network_prefix": "7584"
}
},
"1": {
"0": 1,
"1": "The specified MSISDN is active.",
"2": "4b0eac9b1c84b239447017b04767574b075a4aa1",
"3": "447826987456",
"4": 1,
"5": "234159076621450",
"6": "23415",
"original": {
"country_name": "United Kingdom",
"country_prefix": "44",
"network_name": "Vodafone Ltd",
"network_prefix": "7826"
}
}
}
You can use the json_decode() function in PHP to convert the above strings into a PHP variables.
Sample code
<?php
function hlr($params)
{
$options = array(
CURLOPT_HEADER => FALSE,
CURLOPT_POST => TRUE,
CURLOPT_POSTFIELDS => $params,
CURLOPT_RETURNTRANSFER => TRUE
);
$ch = curl_init('http://api.onesixty.co.uk/rest/v2/hlr');
if ($ch)
{
if (curl_setopt_array($ch, $options))
{
$response = curl_exec($ch);
if ($response)
{
$result = json_decode($response, TRUE);
if ( ! empty($result))
{
if (is_array($result) && isset($result[0]))
{
if ($result[0] > 0)
{
if ($result[4] > 0)
{
//add_to_log("Success: MSISDN ({$result[3]}) is active.");
}
else
{
//add_to_log("Success: MSISDN ({$result[3]}) is inactive.");
}
}
else
{
if (isset($result[3]))
{
//add_to_log("Error: MSISDN ({$result[3]}) - {$result[1]}");
}
else
{
//add_to_log("Error: {$result[1]}");
}
}
return (bool)$result[0];
}
}
}
}
curl_close($ch);
}
return FALSE;
}
$params = http_build_query(array(
'username' => 'MyUsername',
'api_key' => '47acd2028cf81b5da88ddeedb2aea4eca4b71fbd',
'msisdn' => '447123456789'
));
if (hlr($params))
{
echo 'HLR lookup was performed successfully...';
}
?>
Speak to a real person
(01323) 800 160
One direct number for all enquiries - sales and support.
Monday - Friday, 10am to 6pm.
Clear SMS pricing
SMS text messages from just 2.99p. Lower prices available for an agreeable monthly quota.
