HLR API

MessageBird provides an API to send Network Queries to any mobile number across the world.

An HLR allows you to view which mobile number (MSISDN) belongs to what operator in real time and see whether the number is active.

URI

https://rest.messagebird.com/hlr

Available HTTP Methods

POST /hlr
GET /hlr
GET /hlr/{hlrId}
DELETE /hlr/{hlrId}

The HLR object

This object represents a HLR at MessageBird.com

Example object

{
"id":"0da180b035398662ceb3c42h04904985",
"href":"https://rest.messagebird.com/hlr/0da180b035398662ceb3c42h04904985",
"msisdn":31612345678,
"network":20406,
"reference":"YourReference",
"details": {
"status_desc": null,
"imsi": "204080010948431",
"country_iso": "NLD",
"country_name": "Netherlands",
"location_msc": "316530",
"location_iso": 'nl',
"ported": 0,
"roaming": 0
},
"status":"active",
"createdDatetime":"2016-05-04T07:32:46+00:00",
"statusDatetime":"2016-05-04T07:32:46+00:00"
}

Attributes

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
hrefstringThe URL of the created object.
msisdnintThe telephone number.
networkintThe MCCMNC code of the network provider.
referencestringA client reference
detailshashA hash with extra HLR information. See table below for extra information.
statusstringThe status of the msisdns. Possible values: sent, absent, active, unknown, and failed
createdDatetimedatetimeThe date and time of the creation of the message in RFC3339 format (Y-m-dTH:i:sP)
statusDatetimedatetimeThe datum time of the last status in RFC3339 format (Y-m-dTH:i:sP)

The details array

Note that the attributes can change over time and some of them can be null because not all information is available for all countries and provider.

AttributeTypeDescription
status_descstringExtended status information
imsistringIMSI (International Mobile Subscriber Identity) of mobile number
country_isostringCountry ISO code of location of MSISDN
country_namestringCountry name of location of MSISDN
location_mscstringMSC (Mobile Switching Center) of MSISDN
location_isostringCountry ISO of MSC (lowercase ISO 3166-1 alpha-2)
portedintegerIs 1 if the phone number is ported or 0 when the phone number is not ported or ported status is unknown
roamingintegerIs 1 if the phone number is roaming or 0 when the phone number is not roaming or roaming status is unknown

Request an HLR

Creates a new HLR object. MessageBird returns the created HLR object with each request.

Required parameters

ParameterTypeDescription
msisdnintThe telephone number that you want to do a network query on.

Optional parameters

ParameterTypeDescription
referencestringA client reference.

Definition

POST https://rest.messagebird.com/hlr

Example request

curl -X POST https://rest.messagebird.com/hlr \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM' \ -d "msisdn=31612345678" \ -d "reference=YourReference"

Returns

Returns an HLR object if the request was successful. If the request failed, an error object will be returned.

Example response

{
"id":"0da180b035398662ceb3c42h04904985",
"href":"https://rest.messagebird.com/hlr/0da180b035398662ceb3c42h04904985",
"msisdn":31612345678,
"network":null,
"details":[],
"reference":"YourReference",
"status":"sent",
"createdDatetime":"2016-05-04T07:32:46+00:00",
"statusDatetime":"2016-05-04T07:32:46+00:00"
}

View an HLR

Retrieves the information of an existing HLR. You only need to supply the unique message id that was returned upon creation or receiving.

Required parameters

ParameterTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required

Definition

GET https://rest.messagebird.com/hlr/{hlrId}

Example request

curl -X GET https://rest.messagebird.com/hlr/0da180b035398662ceb3c42h04904985 \ -H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Returns

Returns an HLR object if the request was successful. If the request failed, an error object will be returned.

Example response

{
"id":"0da180b035398662ceb3c42h04904985",
"href":"https://rest.messagebird.com/hlr/0da180b035398662ceb3c42h04904985",
"msisdn":31612345678,
"network":20406,
"reference":"YourReference",
"details": {
"status_desc": null,
"imsi": "204080010948431",
"country_iso": "NLD",
"country_name": "Netherlands",
"location_msc": "316530",
"location_iso": 'nl',
"ported": 0,
"roaming": 0
},
"status":"active",
"createdDatetime":"2016-05-04T07:32:46+00:00",
"statusDatetime":"2016-05-04T07:32:46+00:00"
}

Handle an HLR response

HLR responses are requests that are sent to your platform through a GET request. The requests hold information about the requested network query. You can configure your HLR callback url within the API settings.

Attributes

AttributeTypeDescription
idstringA unique random ID which is created on the MessageBird platform and is returned upon creation of the object.
msisdnintThe telephone number.
networkintThe MCCMNC code of the network provider.
referencestringA client reference
statusstringThe status of the msisdn. Possible values: sent, absent, active, unknown, and failed
createdDatetimedatetimeThe date and time of the creation of the message in RFC3339 format (Y-m-dTH:i:sP)
statusDatetimedatetimeThe datum time of the last status in RFC3339 format (Y-m-dTH:i:sP)

Example request

GET http://your-own.url/script?id=e8077d803532c0b5937c639b60216938&msisdn=31612345678&reference=YourReference&status=active&createdDatetime=2016-05-04T07:32:46+00:00&statusDatetime=2016-05-04T07:32:46+00:00

Response

Your platform should respond with a 200 OK HTTP header. When our platform doesn't receive a 200 OK header, we will try to deliver the receipt again (up to 10 times).

Example response

200 OK
cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings