We use cookies to improve your experience on this site and serve more relevant content to you. By continuing to browse our site you agree to our use of cookies, revised Privacy Policy and Terms of Service.  More information about cookies

Number Lookup (HLR)

HLR lookup is a method to determine the current service provider of a mobile subscriber.

POST https://api.vertexsms.com/hlr

Submits the provided msisdn for HLR lookup. If operation is successful - returns HTTP status code 200 OK

Required parameters
Field msisdn
Type string
Description International subscriber number, of which HLR status is desired.
Field callBackUrl
Type url
Description Where to deliver HLR lookup result for the provided msisdn

Request example:

POST /hlr HTTP/1.1
Host: api.vertexsms.com
Content-Type: application/json
Accept: application/json
X-VertexSMS-Token: eB52vNTPL9fO3rDrx8pYmVnj6nqceHNhnqceHNh

{ “msisdn”: “37069912345”, “callBackUrl”: “http://api.vertexsms.com/hlr_callback?myRequestId=123456” }

Response example:

HTTP/1.1 200 OK
Content-Type: application/json
Cache-control: no-cache


HLR Lookup Callback

After an attempt of MSISDN lookup, Vertex server will perform a POST request to your callBackUrl with POST body containing JSON object with HLR data.

Example request (when dlrUrl is set as http://yourserver.com/your_script.php):

POST /your_script.php HTTP/1.1
Host: yourserver.com
Content-Type: application/json

{ “id”: “1203877133”,”error”:”0”, “imsi”:”2460210051600001”, “country”:”LT”, “mcc”:”246”, “mnc”:”021” }

HLR Callback fields explanation
Field id
Type string
Description Unique HLR lookup request identifier, which was returned after submitting a MSISDN for HLR lookup.
Field error
Type integer
Description You can find all VertexSMS API error codes here
Field imsi
Type integer
Description International mobile subscriber identity
Field country
Type string
Description Country code in ISO 3166-1 alpha-2 format
Field operatorId
Type integer
Description Internal VertexSMS operator identifier. More info
Field mcc
Type string
Description Mobile country code MCC list
Field mnc
Type string
Description Mobile network code MNC list
Field ported
Type array
Description This field will not be empty if number is ported to other operator. This will show origin operator information. On ported number this field will contain those values:
operatorId - Internal VertexSMS operator identifier. More info
operator - Operator name
country - Country code in ISO 3166-1 alpha-2 format
Your server response Your script, which will handle message delivery reports coming to callBackUrl MUST respond with HTTP status code 200 OK and response body OK. Otherwise, the callback will be considered failed and will be repeated until it succeeds.