v1 / v2
Example Requests and Responses
Overview
The following is a list of the various requests you can make and the responses you should expect to see.
It shows how you can use the API to lookup single or multiple numbers, and include different optional parameters for each number you enter.
For a detailed explanation of all response fields you can visit this page - Full API Result - Response Body Format and Explanations
Basic single number lookup
Request:
{
"api_key": "mykey",
"api_secret": "mysecret",
"requests": [
{ "telephone_number": "+44(7790) 60 60 23" }
]
}
Note that the use of non numerical characters such as + and brackets is allowed.
Response:
{
"body": {
"results": [
{
"error": "NONE",
"uuid": "f066f711-4043-4d54-847d-c273e6491881",
"request_parameters": {
"telephone_number": "+44(7790) 60 60 23",
"save_to_cache": "YES",
"input_format": "",
"output_format": "",
"cache_days_global": 0,
"cache_days_private": 0,
"get_ported_date": "NO",
"get_landline_status": "NO",
"usa_status": "NO"
},
"credits_spent": 1,
"detected_telephone_number": "447790606023",
"formatted_telephone_number": "",
"live_status": "LIVE",
"original_network": "AVAILABLE",
"original_network_details": {
"name": "EE Limited (Orange)",
"mccmnc": "23433",
"country_name": "United Kingdom",
"country_iso3": "GBR",
"area": "United Kingdom",
"country_prefix": "44"
},
"current_network": "AVAILABLE",
"current_network_details": {
"name": "Virgin Mobile",
"mccmnc": "23438",
"country_name": "United Kingdom",
"country_iso3": "GBR",
"country_prefix": "44"
},
"is_ported": "YES",
"timestamp": "2022-09-08T10:56:03Z",
"telephone_number_type": "MOBILE",
"sms_email": "",
"mms_email": ""
}
]
}
Single number lookup with optional fields
Request:
{
"api_key": "mykey",
"api_secret": "mysecret",
"requests": [
{
"telephone_number": "+44(7540)822-872",
"cache_days_global": 30,
"output_format": "USA",
"get_ported_date": "YES"
}
]
}
Response
{
"body": {
"results": [
{
"error": "NONE",
"uuid": "79bbe7ec-c6be-48d4-a68b-c387b1faa96f",
"request_parameters": {
"telephone_number": "+44(7540)822-872",
"save_to_cache": "YES",
"input_format": "",
"output_format": "USA",
"cache_days_global": 30,
"cache_days_private": 7,
"get_ported_date": "YES",
"get_landline_status": "NO",
"usa_status": "NO"
},
"credits_spent": 1,
"detected_telephone_number": "447540822872",
"formatted_telephone_number": "011 44 7540 822872",
"live_status": "LIVE",
"original_network": "AVAILABLE",
"original_network_details": {
"name": "O2 (UK)",
"mccmnc": "23410",
"country_name": "United Kingdom",
"country_iso3": "GBR",
"area": "United Kingdom",
"country_prefix": "44"
},
"current_network": "AVAILABLE",
"current_network_details": {
"name": "EE Limited (T-Mobile)",
"mccmnc": "23430",
"country_name": "United Kingdom",
"country_iso3": "GBR",
"country_prefix": "44"
},
"is_ported": "YES",
"timestamp": "2022-09-08T10:04:27Z",
"telephone_number_type": "MOBILE",
"sms_email": "07540822872@t-mobile.uk.net",
"mms_email": "",
"ported_date": "NOT_AVAILABLE"
}
]
}
Note - This account has a default Private Cache setting of 7 days.
Multiple number lookup with optional fields
Request:
{
"api_key": "mykey",
"api_secret": "mysecret",
"requests": [
{ "telephone_number": "+449043910781", "cache_days_global": 30 },
{
"telephone_number": "1373",
"cache_days_global": 30,
"output_format": "USA"
}
]
}
Response:
{
"body": {
"results": [
{
"error": "NONE",
"uuid": "7fe27469-87d9-4a6b-95f3-c0884e084cd2",
"request_parameters": {
"telephone_number": "+449043910781",
"save_to_cache": "YES",
"input_format": "",
"output_format": "",
"cache_days_global": 30,
"cache_days_private": 0,
"get_ported_date": "NO",
"get_landline_status": "NO",
"usa_status": "NO"
},
"credits_spent": 0,
"detected_telephone_number": "449043910781",
"formatted_telephone_number": "",
"live_status": "NO_COVERAGE",
"original_network": "NOT_AVAILABLE",
"original_network_details": {
"name": "",
"mccmnc": "",
"country_name": "United Kingdom",
"country_iso3": "GBR",
"area": "United Kingdom",
"country_prefix": "44"
},
"current_network": "NOT_AVAILABLE",
"current_network_details": {},
"is_ported": "UNKNOWN",
"timestamp": "2022-09-08T11:05:12Z",
"telephone_number_type": "PREMIUM",
"sms_email": "",
"mms_email": "",
"disposable_number": "UNKNOWN"
},
{
"error": "NONE",
"uuid": "9fa25b01-4d85-41b5-90d9-c0fda876f785",
"request_parameters": {
"telephone_number": "1373",
"save_to_cache": "YES",
"input_format": "",
"output_format": "USA",
"cache_days_global": 30,
"cache_days_private": 0,
"get_ported_date": "NO",
"get_landline_status": "NO",
"usa_status": "NO"
},
"credits_spent": 0,
"detected_telephone_number": "",
"formatted_telephone_number": "",
"live_status": "NOT_APPLICABLE",
"original_network": "NOT_APPLICABLE",
"original_network_details": {},
"current_network": "NOT_APPLICABLE",
"current_network_details": {},
"is_ported": "UNKNOWN",
"timestamp": "2022-09-08T11:05:12Z",
"telephone_number_type": "BAD_FORMAT",
"sms_email": "",
"mms_email": ""
}
]
}
UNAUTHORIZED
Curl is used for this example.
Request:
curl -H "Content-Type: application/json" -X POST -d '{"api_key":"wrongkey", "api_secret":"wrongsecret", "requests":[{"telephone_number": "+44(7790) 60 60 23"}]}' http://api.hlrlookup.com/apiv2/hlr
Response:
Header:
HTTP/1.1 401 Unauthorized
Content-Type: application/json; charset=utf-8
Content-Length: 66
Body:
{ "error": "UNAUTHORIZED", "message": "Invalid api_key or api_secret" }