API Reference

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

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.


API Endpoint

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

API Endpoint

https://rest.messagebird.com/lookup

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

GET /lookup/{phoneNumber}
GET /lookup/{phoneNumber}/hlr
POST /lookup/{phoneNumber}/hlr

The Lookup object

This object represents a Lookup at MessageBird.com

Attributes

AttributeTypeDescription
hrefstringThe URL of this lookup.
countryCodestringThe country code for this number in ISO 3166-1 alpha-2 format.
countryPrefixintegerThe country calling code for this number.
phoneNumberintegerThe phone number in E.164 format without the prefixed plus-sign.
typestringThe 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.
formatshashA hash containing references to this phone number in several different formats.
formats.e164stringThe phone number in E.164 format.
formats.internationalstringThe phone number in international format.
format.nationalstringThe phone number in national/local format.
format.rfc3966stringThe phone number in RFC3966 format.
hlrhashThe most recent HLR object. If no such HLR objects exists, this hash won't be returned.
hlr.idstringA unique random ID which is created on the MessageBird platform.
hlr.networkintThe MCCMNC code of the network provider.
hlr.referencestringA client reference.
hlr.statusstringThe status of the HLR request. Possible values: sent, absent, active, unknown, and failed.
hlr.createdDatetimedatetimeThe date and time of the creation of the message in RFC3339 format (Y-m-d\TH:i:sP).
hlr.statusDatetimedatetimeThe 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

ParameterTypeDescription
phoneNumberintThe telephone number that you want to look up.

Optional parameters

ParameterTypeDescription
countryCodestringIf the phoneNumber parameter is in a national format, this parameter is required to figure out the international format.

Definition

GET https://rest.messagebird.com/lookup/{phoneNumber}

Example request

curl -X GET https://rest.messagebird.com/lookup/31612345678 \
-H 'Authorization: AccessKey test_gshuPaZoeEG6ovbc8M79w0QyM'

Response

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

Example response

{
"href":"https://rest.messagebird.com/lookup/31612345678",
"countryCode":"NL",
"countryPrefix":31,
"phoneNumber":31612345678,
"type":"mobile",
"formats":{
"e164":"+31612345678",
"international":"+31 6 12345678",
"national":"06 12345678",
"rfc3966":"tel:+31-6-12345678"
}
}

Request an HLR

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

Required parameters

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

Optional parameters

ParameterTypeDescription
referencestringA client reference.
countryCodestringIf the phoneNumber parameter is in a national format, this parameter is required to figure out the international format.

Definition

POST https://rest.messagebird.com/lookup/{phoneNumber}/hlr

Example request

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

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

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

Optional parameters

ParameterTypeDescription
countryCodestringIf the phoneNumber parameter is in a national format, this parameter is required to figure out the international format.

Definition

GET https://rest.messagebird.com/lookup/{phoneNumber}/hlr

Example request

curl -X GET https://rest.messagebird.com/lookup/31612345678/hlr \
-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 from requests sent via the /lookup URL are handled exactly the same as HLR responses sent via the /hlr URL.

Next upContacts

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