API Reference

OverviewSMSSMS batch APIVoice CallingVoice MessagingConversations APIContacts API (v2)Integrations APIFile Storage APIOmnichannel WidgetNumbersPartner AccountsVerifyMMSHLRBalanceLookupContactsGroupsIntentFAQNamed Entity RecognitionLanguage Detection

HLR API

MessageBird’s HLR API provides a way to send Network Queries to any mobile number globally. It allows you to view what mobile number (MSISDN) belongs to what operator in real-time and see if the number is active.

The HLR API uses HTTP verbs and a RESTful endpoint structure with an access key that is used as the API Authorization framework. Request and response payloads are formatted as JSON—although we provide a GET alternative for requests—using UTF-8 encoding and URL encoded values.


API Endpoint

All URLs referenced in MessageBird's HLR Messaging API documentation have the base URL in the code snippet on the right side:

API Endpoint

https://rest.messagebird.com/hlr

Available HTTP methods

The MessageBird API uses HTTP verbs to understand if you want to read (GET), delete (DELETE) or create (POST) an object. When your web application cannot do a POST or DELETE, we provide the ability to set the method through the query parameter _method.

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-d\TH:i:sP)
statusDatetimedatetimeThe datum time of the last status in RFC3339 format (Y-m-d\TH: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-d\TH:i:sP)
statusDatetimedatetimeThe datum time of the last status in RFC3339 format (Y-m-d\TH: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
Next upBalance

Questions?

We’re always happy to help with code or other doubts you might have! Check out our Quickstarts, API Reference, Tutorials, SDKs, or contact our Support team.

Cookie Settings