API-SMS Documentation: Verification by HLR Lookup

POST

https://api.octopush.com/v1/public/contact/hlr-request

Encoding : UTF-8

Authentication

Your “api-key” and “api-login” must be added in the headers.

Definition

Allows you to check the validity of a telephone line.

Special parameters

Field	Type	Description
phone_numbers	string[]	Telephone numbers in international format +XXZZZZZ : [ "+123123", "+132323", ... ]
simulation_mode	boolean	(optional) If this field is set to “true”, your query will be simulated, and you will receive a false result. Only a few validations will be performed.

Curl Example

curl -X POST \ 
'https://api.octopush.com/v1/public/contact/hlr-request' \ 
-H 'Content-Type: application/json' \ 
-H 'api-login: ******@email.org' \ 
-H 'api-key: ************' \ 
-H 'cache-control: no-cache' \ 
-d '
{
  "phone_numbers": [
    "+33611223344",
    "+33611223345",
    "+33611223346" 
}'

Command to copy/paste

curl -X POST 'https://api.octopush.com/v1/public/contact/hlr-request' -H 'Content-Type: application/json' -H 'api-login: ******@email.org' -H 'api-key: ************' -H 'cache-control: no-cache' -d '{"phone_numbers": ["+33611223344","+33611223345","+33611223346"]}'

JSON Server Response

Success : 200 Created

[
  {
    "network_name": "Bouygues Telecom",
    "mcc": 208,
    "mnc": 21,
    "status": "valid",
    "country_name": "France",
    "country_code_iso3": "FRA",
    "country_code": "FR",
    "area": "France Métropolitaine",
    "country_prefix": "+33",
    "phone_number": "+33611223344",
    "phone_number_type": "mobile",
    "line_status": "live",
    "is_ported": true,
    "ported_date": '2021-10-04 14:00:14',
    "original_network_details": {
      "network_name": "SFR",
      "mcc": 208,
      "mnc": 9,
      "country_name": "France",
      "country_code_iso3": "FRA",
      "country_code": "FR",
      "area": "France Métropolitaine",
      "country_prefix": "+33",
    }
  },
  {
    "network_name": "SFR",
    "mcc": 208,
    "mnc": 9,
    "status": "invalid",
    "country_name": "France",
    "country_code_iso3": "FRA",
    "country_code": "FR",
    "area": "France Métropolitaine",
    "country_prefix": "+33",
    "phone_number": "+33611223345",
    "phone_number_type": "mobile",
    "line_status": "dead",
    "is_ported": false,
    "ported_date": null,
    "original_network_details": null
  },
  {
    "network_name": "Free",
    "mcc": 208,
    "mnc": 15,
    "status": "unknown",
    "country_name": "France",
    "country_code_iso3": "FRA",
    "country_code": "FR",
    "area": "France Métropolitaine",
    "country_prefix": "+33",
    "phone_number": "+33611223346",
    "phone_number_type": "mobile",
    "line_status": "inconcusive",
    "is_ported": false,
    "ported_date": null,
    "original_network_details": null
  }
]

Failure : 400 BAD REQUEST

{
  "code": 400,
  "message": "Payload validation error.",
  "errors": {
    "phone_number": {
      "code": 410,
      "message": "This value should not be blank."
    }
  }
}

Specific limitations

1 to 200 numbers per request.

Returned parameters

Field	Type	Description
network_name	string	Netword name
mnc	interger	Network Network Code
mcc	integer	Network Country Code
status	string	Is the number valid or not ?
country_name	string	Name of the phone number country.
country_code_iso3	string	Country code of the phone number (3 letters)
country_code	string	Country code of the phone number (2 letters).
area	string	Geographical zone of the mobile line.
country_prefix	string	Number prefix.
phone_number	string	Formatted phone number.
phone_number_type	string	Type of the phone. Possible values and definitions are described in the dictionary.
line_status	string	Status of the line, depending last date of synchronisation to network, if line does exist and does have a owner.
is_ported	boolean	Indicate if the number has been ported or not from the original network to the current network.
ported_date	string	Date when the number has been ported. Format YYYY-MM-DD HH:II:SS
original_network_details	string	Information about the original network. Will contain network_name, mcc, mnc, country_name, country_code_iso3, country_code, area, country_prefix

Return dictionary

Value	Definition
status
valid	The line has a owner.
invalid	The line does not have a owner.
operator_is_not_available	Impossible de get the information.
unknown	Unknown status.
line_status
live	This phone number is live and is assigned to a subscriber who has recently used their phone.
dead	This phone number has been confirmed to be a dead phone number by the phone network and will not receive phone calls or text messages because the phone number is not assigned to an existing SIM card or user.
absent_subscriber	This phone 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 phone 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 phone number is assigned to a SIM card which is not allowed to make or receive phone calls. Typically a “data only SIM”.
not_available_network_only	The phone network who owns the phone number does not provide Live/Dead type status, but will provide porting information if the phone number has been ported to another network.
no_coverage	We do not currently have coverage to detect the live status for this phone network.
not_applicable	Used if there is no detected phone number.
inconclusive	We were currently unable to ascertain the status for this number.
phone_type
bad_format	the number you submitted to be checked could not be identified as a valid international phone number.
mobile	a phone number assigned to a mobile phone operator / cell phone operator.
landline	a fixed wired phone in a fixed location such as home or office.
mobile_or_landline	where the phone 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 phone bill. the callee typically receives revenue from the call.
shared_cost	this phone 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 phone 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 phone 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 phone number instead of multiple phone numbers.
personal_number	a phone 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.

Menu

HLR Lookup – Number Verification