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.
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
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. |
| href | string | The URL of the created object. |
| msisdn | int | The telephone number. |
| network | int | The MCCMNC code of the network provider. |
| reference | string | A client reference |
| details | hash | A hash with extra HLR information. See table below for extra information. |
| status | string | The status of the msisdns. Possible values: sent, absent, active, unknown, and failed |
| createdDatetime | datetime | The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP) |
| statusDatetime | datetime | The 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.
| Attribute | Type | Description |
|---|---|---|
| status_desc | string | Extended status information |
| imsi | string | IMSI (International Mobile Subscriber Identity) of mobile number |
| country_iso | string | Country ISO code of location of MSISDN |
| country_name | string | Country name of location of MSISDN |
| location_msc | string | MSC (Mobile Switching Center) of MSISDN |
| location_iso | string | Country ISO of MSC (lowercase ISO 3166-1 alpha-2) |
| ported | integer | Is 1 if the phone number is ported or 0 when the phone number is not ported or ported status is unknown |
| roaming | integer | Is 1 if the phone number is roaming or 0 when the phone number is not roaming or roaming status is unknown |
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
| Parameter | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. Required |
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
| Attribute | Type | Description |
|---|---|---|
| id | string | A unique random ID which is created on the MessageBird platform and is returned upon creation of the object. |
| msisdn | int | The telephone number. |
| network | int | The MCCMNC code of the network provider. |
| reference | string | A client reference |
| status | string | The status of the msisdn. Possible values: sent, absent, active, unknown, and failed |
| createdDatetime | datetime | The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP) |
| statusDatetime | datetime | The datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP) |
