Lookup API
MessageBird's Lookup API enables you to validate and look up a mobile number. You supply our API with the phone numbers you’d like to check, our API performs an HLR Lookup on the mobile network and identifies the number format, and we fill in the number data, along with availability and provider. The Lookup API will help you keep your database clean.
A phone number validation will tell you if the specified phone number looks valid. It will also include some alternative formats to display the phone number in. An HLR lookup allows you to view which mobile number (MSISDN) belongs to what operator in real-time and see whether the number is active.
The Lookup 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.
The Lookup object
This object represents a Lookup at MessageBird.com
Attributes
| Attribute | Type | Description |
|---|---|---|
| href | string | The URL of this lookup. |
| countryCode | string | The country code for this number in ISO 3166-1 alpha-2 format. |
| countryPrefix | integer | The country calling code for this number. |
| phoneNumber | integer | The phone number in E.164 format without the prefixed plus-sign. |
| type | string | The type of number. This can be fixed line, mobile, fixed line or mobile, toll free, premium rate, shared cost, voip, personal number, pager, universal access number, voice mail or unknown. |
| formats | hash | A hash containing references to this phone number in several different formats. |
| formats.e164 | string | The phone number in E.164 format. |
| formats.international | string | The phone number in international format. |
| format.national | string | The phone number in national/local format. |
| format.rfc3966 | string | The phone number in RFC3966 format. |
| hlr | hash | The most recent HLR object. If no such HLR objects exists, this hash won't be returned. |
| hlr.id | string | A unique random ID which is created on the MessageBird platform. |
| hlr.network | int | The MCCMNC code of the network provider. |
| hlr.reference | string | A client reference. |
| hlr.status | string | The status of the HLR request. Possible values: sent, absent, active, unknown, and failed. |
| hlr.createdDatetime | datetime | The date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP). |
| hlr.statusDatetime | datetime | The datum time of the last status in RFC3339 format (Y-m-d\TH:i:sP). |
Request a lookup
Performs a new lookup for the specified number. MessageBird returns a Lookup object with each request.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| phoneNumber | int | The telephone number that you want to look up. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| countryCode | string | If the phoneNumber parameter is in a national format, this parameter is required to figure out the international format. |
Response
Returns a Lookup object if the request was successful. If the request failed, an error object will be returned.
Request an HLR
Creates a new HLR object. MessageBird returns the created HLR object with each request.
Required parameters
| Parameter | Type | Description |
|---|---|---|
| phoneNumber | int | The telephone number that you want to do a network query on. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| reference | string | A client reference. |
| countryCode | string | If the phoneNumber parameter is in a national format, this parameter is required to figure out the international format. |
Response
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 |
|---|---|---|
| phoneNumber | int | The telephone number that you want to do a network query on. |
Optional parameters
| Parameter | Type | Description |
|---|---|---|
| countryCode | string | If the phoneNumber parameter is in a national format, this parameter is required to figure out the international format. |
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 from requests sent via the /lookup URL are handled exactly the same as HLR responses sent via the /hlr URL.
