Skip to content
Home » Octopush Gateway SMS API » HLR Lookup – Number Verification

HLR Lookup – Number Verification

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

FieldTypeDescription
phone_numbersstring[]Telephone numbers in international format +XXZZZZZ :
[
  "+123123", 
  "+132323",
  ...
]
simulation_modeboolean(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

FieldTypeDescription
network_namestringNetword name
mncintergerNetwork Network Code
mccintegerNetwork Country Code
statusstringIs the number valid or not ?
country_namestringName of the phone number country.
country_code_iso3stringCountry code of the phone number (3 letters)
country_codestringCountry code of the phone number (2 letters).
areastringGeographical zone of the mobile line.
country_prefixstringNumber prefix.
phone_numberstringFormatted phone number.
phone_number_typestringType of the phone. Possible values and definitions are described in the dictionary.
line_statusstringStatus of the line, depending last date of synchronisation to network, if line does exist and does have a owner.
is_portedbooleanIndicate if the number has been ported or not from the original network to the current network.
ported_datestringDate when the number has been ported. Format YYYY-MM-DD HH:II:SS
original_network_detailsstringInformation about the original network. Will contain network_name, mcc, mnc, country_name, country_code_iso3, country_code, area, country_prefix

Return dictionary

ValueDefinition

status

validThe line has a owner.
invalidThe line does not have a owner.
operator_is_not_availableImpossible de get the information.
unknownUnknown status.

line_status

liveThis phone number is live and is assigned to a subscriber who has recently used their phone.
deadThis 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_subscriberThis 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_provisionedThe 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_onlyThe 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_coverageWe do not currently have coverage to detect the live status for this phone network.
not_applicableUsed if there is no detected phone number.
inconclusiveWe were currently unable to ascertain the status for this number.

phone_type

bad_formatthe number you submitted to be checked could not be identified as a valid international phone number.
mobilea phone number assigned to a mobile phone operator / cell phone operator.
landlinea fixed wired phone in a fixed location such as home or office.
mobile_or_landlinewhere the phone number could belong to either a mobile or landline type phone.
toll_freealso 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.
premiumthere 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_costthis 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.
voipassigned to a voip provider who delivers calls and text messages over the internet to the end user or service.
stage_and_screenreserved 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.
pagerallocated to a device that receives and displays numeric or alphanumeric messages.
universal_access_numbera 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_numbera 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_onlyaccess number for voicemail only.
unknownAny number which does not fall into any of the above categories.