Full API Result - Response Body Format and Explanations

v1 / v2

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:


  • 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:


  • 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.