Full API Result - Response Body Format and Explanations
Overview
For any HTTP 200 response the response body will be JSON formatted with the following general layout:
{
"body": {
"results": [
{
"error": "NONE",
"uuid": "4562ab7e-af26-4d42-87a0-b84bb4e5f96c",
"request_parameters": {
"telephone_number": "447540822872",
"save_to_cache": "NO",
"input_format": "",
"output_format": "GBR",
"cache_days_global": 14,
"cache_days_private": 7,
"get_ported_date": "YES",
"get_landline_status": "YES",
"usa_status": "YES"
},
"credits_spent": 1,
"detected_telephone_number": "447540822872",
"formatted_telephone_number": "07540 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-10-07T13:06:15Z",
"telephone_number_type": "MOBILE",
"ported_date": "NOT_AVAILABLE"
}
]
}Response Field descriptions - Part 1
error
Type: String - To be exactly matched
{ "error": "NONE" } Possible values:
NONE - No errors were received when submitting your request to the service.
INSUFFICIENT_CREDIT - There is no credit available on the api_key you used.
INTERNAL_ERROR - We encountered an error we were not expecting.
uuid
Type: String
Example:
{ "uuid": "73f59ce5-6ee9-4e52-b7c8-d3b4669abcbf" }Value:
A unique identifier for this response.
request_parameters.telephone_number
Type: String
Example:
"request_parameters": {"telephone_number": "447540822872"},Value:
The string you submitted in the telephone_number field lookup for this response. If you have submitted multiple telephone numbers in your request, use this field to match your individual telephone number request to this individual response.
request_parameters.cache_days_private
Type: Integer
Example:
"request_parameters": {"cache_days_private": 7},Value:
The number of days we checked back in the private cache. If you did not submit the optional cache_days_private parameter in your request then the default value will be used and cache_days_private will show the default value.
request_parameters.cache_days_global
Type: Integer
Example:
"request_parameters": {"cache_days_global": 14},Value:
The number of days we checked back in the Global Cache. If you did not submit the optional cache_days_global parameter in your request then the default value will be used and cache_days_global will show the default value.
request_parameters.save_to_cache
Type: String
Example:
"request_parameters": {"save_to_cache": "NO"},Value:
The value we used for save_to_cache. If you did not submit the optional save_to_cache parameter in your request then the default value YES will be used.
request_parameters.output_format
Type: String - To be exactly matched
Example:
"request_parameters": {"output_format": "GBR"},Possible Values:
E164
PLUS_E164
Iso3 country code
"" (empty string if parameter was not requested)
request_parameters.input_format
Type: String - To be exactly matched
Example:
"request_parameters": {"input_format": ""},Possible Values:
Any single Iso3 country code E.g. USA or FRA or GBR etc.
request_parameters.get_ported_date
Type: String - To be exactly matched
Example:
"request_parameters": {"get_ported_date": "YES"},Possible Values:
YES
NO
"" (empty sting if parameter not requested)
request_parameters.get_landine_status
Type: String - To be exactly matched
Example:
"request_parameters": {"get_landline_status": "YES"},Possible Values:
YES
NO
"" (empty sting if parameter not requested)
request_parameters.usa_status
Type: String
Example:
"request_parameters": {"usa_status": "YES"},Possible Values:
YES
NO
"" (empty sting if parameter not requested)
Response Field descriptions - Part 2
credits_spent
Type: Float
Example:
"credits_spent": 1,Value:
The number of credits used to lookup this individual number. If no credits were spent then this will be 0. If one credit was spent then this will be 1. If two credits were spent this will be 2, etc.
Please parse the full float to 1 decimal place to allow for future changes (e.g. service which consumes 1.5 or 0.5 credits).
detected_telephone_number
Type: String
Example:
"detected_telephone_number": "447540822872",Value:
Standardised E164 format of the detected telephone number which conforms to a valid telephone number including matching an existing dialable international country code and an assigned local area to an existing telecommunications company and matching the correct number of digits for that country and area and number type.
If no telephone number is possible from the requested_number this field will be an empty string.
formatted_telephone_number
Type: String
Example:
"formatted_telephone_number": "447540 822872",Value:
If a telephone number has been detected then the detected_telephone_number is displayed in your requested output format.
If you did not specify the optional output_format in your request then this field will default to an empty string.
live_status
Type: String - To be exactly matched
Example:
"live_status": "LIVE",Table of possible values:
Value | Explanation |
|---|---|
LIVE | This telephone number is live and is assigned to a subscriber who has recently used their telephone |
DEAD | This telephone number has been confirmed to be a dead telephone number by the telephone network and will not receive telephone calls or text messages because the telephone number is not assigned to an existing SIM card or user |
ABSENT_SUBSCRIBER | This telephone number is assigned to a mobile SIM card, but either: 1. There has been a prolonged period of inactivity from the mobile handset 2. The mobile phone has been turned off, or gone out of radio coverage, and someone has attempted to call or send an SMS to the telephone number 3. The number is allocated to a new SIM card and the SIM card has not yet been registered to a user |
NO_TELESERVICE_PROVISIONED | The telephone number is assigned to a SIM card which is not allowed to make or receive telephone calls. Typically a “data only SIM”. |
NOT_AVAILABLE_NETWORK_ONLY | The telephone network who owns the telephone number does not provide Live/Dead type status, but will provide porting information if the telephone number has been ported to another network |
NO_COVERAGE | We do not currently have coverage to detect the live status for this telephone network |
NOT_APPLICABLE | Used if there is no detected telephone number |
INCONCLUSIVE | We were currently unable to ascertain the status for this number |
telephone_number_type
Type: String - To be exactly matched
Example:
"telephone_number_type": "MOBILE",Table of possible values:
Value | Explanation |
|---|---|
BAD_FORMAT | The number you submitted to be checked could not be identified as a valid international telephone number |
MOBILE | A phone number assigned to a Mobile Telephone Operator / Cell Phone Operator |
LANDLINE | A fixed wired telephone in a fixed location such as home or office |
MOBILE_OR_LANDLINE | Where the telephone number could belong to either a mobile or landline type phone |
TOLL_FREE | Also called Freephone. The number can be called from within the home country at no cost. There may be a charge to call this number from outside the home country |
PREMIUM | There is a premium charge added to call this number, often there is a service provided on the number and by calling the number the user pays for the service using their telephone bill. The callee typically receives revenue from the call |
SHARED_COST | This telephone number will charge both the caller and callee at the same time. There will be an additional charge to call this type of number |
VOIP | Assigned to a VoIP provider who delivers calls and text messages over the internet to the end user or service |
STAGE_AND_SCREEN | Reserved by a regulatory body specifically for use with stage and screen for example used in films when speaking a telephone number. No real end user will be assigned to this number and often they are used as fictitious numbers. |
PAGER | Allocated to a device that receives and displays numeric or alphanumeric messages |
UNIVERSAL_ACCESS_NUMBER | A single telephone number which can be used to route calls to multiple destinations depending on parameters such as time of day, where the caller resides, capacity or more. This is not linked to any specific locality within the country. Typically used by companies to provide a single telephone number instead of multiple telephone numbers |
PERSONAL_NUMBER | A telephone number intended to be used by individuals which may route to multiple locations (home, office and cell phone. Some PERSONAL_NUMBERs are charged at a PREMIUM number rate |
VOICEMAIL_ONLY | Access number for voicemail only |
UNKNOWN | Any number which does not fall into any of the above categories or error=INSUFFICIENT_CREDIT or error=INTERNAL_ERROR |
Response Field Description - Part 3 - Original Network
original_network
Type: String - To be exactly matched
Example:
"original_network_details": "AVAILABLE",Possible Values:
AVAILABLE
Information about the telephone network that originally assigned this telephone number is available. Expect original_network_details to be populated.
NOT_AVAILABLE
Information about the telephone network that originally assigned this telephone number is not available. Expect original_network_details to be an empty object. Like this:
"original_network_details": {},NOT_APPLICABLE
This number can not be allocated to a telephone network, for example BAD_FORMAT. Expect original_network_details to be an empty object. Like this:
"original_network_details": {},original_network_details
Type: JSON Object
Possible Values:
{} (null object - if original_network = NOT_AVAIALABLE or NOT_APPLICABLE)
JSON object with one of the following key/value pairs
name
mccmnc
country_name
country_iso3
area
country_prefix
original_network_details.name
Type: String
Example:
"original_network_details": { "name": "O2 (UK)"},Value:
The name of the telephone network who has been assigned this telephone number range. This can change over time due to company name changes, mergers, acquisitions and re-allocation of a number range by a country’s numbering regulator.
original_network_details.mccmnc
Type: String - To be exactly matched
Example:
"original_network_details": { "mccmnc": "23410"},Possible Values:
"" An empty string if telephone_number was not assigned from a mobile phone operator.
The MCCMNC for the mobile telephone network who has been assigned the telephone number.
original_network_details.country_name
Type: String
Example:
"original_network_details": { "country_name": "United Kingdom"},Value:
The string name of the country where the telephone_number is allocated.
original_network_details.country_iso3
Type: String - To be exactly matched
Example:
"original_network_details": { "country_iso3": "GBR"},Value:
The three letter ISO3 code for the country where the telephone numbers was originally allocated.
original_network_details.area
Type: String
Example:
"original_network_details": { "area": "United Kingdom"},Value:
Where possible the geographic location that the telephone number area code is allocated from. For example this might be a city name for a geographic landline number or a country name for a (non-geographic) mobile number.
original_network_details.country_prefix
Type: String - To be exactly matched
Example:
"original_network_details": { "country_prefix": "44"},Value:
Country dialling prefix for the detected country.
Response Field Description - Part 4 - Current Network
current_network
Type: String - To be exactly matched
Example:
"current_network": "AVAILABLE",Possible Values:
AVAILABLE
Information about the telephone network that this telephone number is currently assigned to is available. Expect current_network_details to be populated.
NOT_AVAILABLE
Information about the telephone network that this telephone number is currently assigned to is not available. Expect current_network_details to be an empty object. Like this:
"current_network_details": {},NOT_APPLICABLE
It is not possible to detect the current network where this telephone number is assigned. For example BAD_FORMAT, NO_COVERAGE, DEAD, INCONCLUSIVE . Expect current_network_details to be an empty object. Like this:
"current_network_details": {},current_network_details
Type: JSON object
Possible Values:
{} (null object if original_network = NOT_AVAILABLE or NOT_APPLICABLE)
JSON object with key/value pairs:
name
mccmnc
country_name
country_iso3
country_prefix
current_network_details.name
Type: String
Example:
"current_network_details": { "name": "EE Limited (T-Mobile)"},Value:
The name of the telephone network where this telephone number is currently assigned. This can change over time due to company name changes, mergers and acquisitions.
current_network_details.mccmnc
Type: String - To be exactly matched
Example:
"current_network_details": { "mccmnc": "23430"},Possible Values:
"" Empty if telephone is not assigned to a mobile telephone operator.
The MCCMNC for the mobile telephone network where this number is currently assigned.
current_network_details.country_name
Type: String
Example:
"current_network_details": { "country_name": "United Kingdom"},
Value:
The string name of the country where this telephone number is allocated.
current_network_details.country_iso3
Type: String - To be exactly matched
Example:
"current_network_details": { "country_iso3": "GBR"},Value:
The three letter ISO3 code for the country where the telephone number was originally allocated.
current_network_details.country_prefix
Type: String - To be exactly matched
Example:
"current_network_details": { "country_prefix": "44"},Value:
Country dialling prefix for the detected country.
Response Field Descriptions - Part 5
is_ported
Type: String - To be exactly matched
Example:
"is_ported": "YES",Possible Values:
YES
This telephone number has been ported from the original network to the current network.
NO
This telephone number has not been ported from the original network to the current network.
UNKNOWN
We have not confirmed if this telephone number has been ported or not.
ported_date
Optional field, only returned when requested.
Type: String or ISO8601 String - To be exactly matched
Example:
"ported_date" : "NOT_AVAILABLE"Possible Values:
NOT_AVAILABLE
No ported date was found for this telephone number.
NOT_APPLICABLE
ported_date is not available because the telephone number might be invalid or telephone number is not a mobile or ported_date is not available for this network.
The ISO 8601 format for the date and time that this detected_telephone_number was last ported.
landline_status
Optional field, only returned when requested and number identified as landline.
Type: String - To be exactly matched
Example:
"landline_status": "LIVE",Table of possible values:
landline_status | status |
|---|---|
LIVE | LIVE |
DEAD | DEAD |
OUT_OF_ORDER | DEAD |
NUMBER_CHANGED | DEAD |
CALL_BARRED | LIVE |
INCONCLUSIVE | INCONCLUSIVE |
UNKNOWN_NOT_AUTH | INCONCLUSIVE |
UNKNOWN_NOT_AVAIL | INCONCLUSIVE |
UNKNOWN_NOT_IMPL | INCONCLUSIVE |
UNKNOWN_REJECTED | INCONCLUSIVE |
UNKNOWN_INTERWORKING | INCONCLUSIVE |
ERROR_UNKNOWN_RESPONSE | INCONCLUSIVE |
timestamp
Type: ISO8601 String - To be exactly matched
Example:
"timestamp" : "2022-03-21T16:02:03Z"Value:
The ISO 8601 format for the date and time that this record was checked. If the number was retrieved from the cache then the date and time the number was originally looked up will be returned.