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" }