Lookup API

MessageBird's Lookup API enables you to validate and look up a mobile number..

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.

URI

https://rest.messagebird.com/lookup

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-dTH:i:sP).
hlr.statusDatetimedatetimeThe datum time of the last status in RFC3339 format (Y-m-dTH: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

$MessageBird = new \MessageBird\Client('ACCESS_KEY');
$Lookup = $MessageBird->lookup->read(31612345678);

Returns

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"

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
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.

cURL
PHP
Node
C#
Java
Ruby
Go
Python
Cookie Settings