Welcome

With MessageHub HLR API you can maximize the performance of your campaigns and your business communication. Validate mobile number databases, remove invalid entries and receive correct portability information, identifying the operators that the mobile numbers belong to.

The HLR API is based on REST. It uses built-in HTTP authentication and HTTP status codes. All data exchange is done in JSON format.

To test MessageHub HLR API, you will need a valid API account. If you don't have one yet please register your account.

Examples

Authentication Endpoint

https://app.messagehub.nl/apis/auth/

OTP API Endpoint

https://app.messagehub.nl/apis/hlr/v2/

Each request must be accompanied by a valid access_token. access_token are generated upon successful authentication. To authenticate you must send an auth request.

https://app.messagehub.nl/apis/auth/

This request accepts parameters type with value access_token, username and password.

access_token

refresh_token

Examples

Authentication

POST https://app.messagehub.nl/apis/auth/

POST https://app.messagehub.nl/apis/auth/
Content-Type : application/json
{
"type" : "access_token",
"username" : "myusername",
"password" : "mypassword"
}

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"access_token" : "dcec4eb6-035c-41a4-9871-82c5bd3ef379",
"validity_period" : 1800,
"refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641"
}
}

Refresh Connection

POST https://app.messagehub.nl/apis/auth/
Content-Type : application/json
{
"type" : "refresh_token",
"refresh_token" : "d32dc41f-6545-4bdc-a980-79e376bbd641",
}

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"access_token" : "0e3f6ecb-7a7e-4d03-a004-d710db8978ab",
"validity_period" : 1800,
"refresh_token" : "ecbb4d30-6da2-4b78-998e-d01025c648f2"
}
}

To lookup a number with an HLR lookup, you must send a /{mobile} GET request.

https://app.messagehub.nl/apis/hlr/v2/{mobile}

Replace /{mobile} with the recipient mobile number phone in international E.164 format.

Remember to setup the Authorization HTTP header with your access_token.

Congratulations! You just made your first number lookup using the HLR API.

If the request succeeded, an object is returned, which includes the status of the mobile queried, as well as additional information regarding the mobile. Some information may not be available, due to restrictions e n forced by national telecommunication authorities and mobile operators. Otherwise, an error is returned.

Examples

Authentication

GET https://app.messagehub.nl/apis/hlr/v2/{mobile}

GET https://app.messagehub.nl/apis/hlr/v2/447778547861

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"phone" : "447778547861",
"status" : "valid",
"mcc" : "202",
"mnc" : "005",
"imsi" : "202052500000000",
"msc" : "30942191",
"cost" : "0.0040",
"country" : "United Kingdom(+44)",
"operator" : "Vodafone UK"
}
}

To get your account's balance you must send a balance GET request.

https://app.messagehub.nl/apis/hlr/v2/balance/

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account balance. Otherwise, an error is returned.

Examples

Get Balance

GET https://app.messagehub.nl/apis/hlr/v2/balance/

GET https://app.messagehub.nl/apis/hlr/v2/balance/
Content-Type : application/json

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"balance" : "7845.3500"
}
}

HLR API uses 2 levels of errors. Conventional HTTP status codes and application error codes.

HLR API raises errors for many reasons (authentication, invalid telephone in URI, network / server errors etc.). Consult the detailed HTTP status codes and application error codes tables for detailed explanation of response codes.

Application Errors

Examples

Errors

{
"status_code" : 404,
"status_message" : "Not found",
"errors" : [
{
"code" : 1007,
"message" : "URI not found"
}
]
}

HTTP Status Codes

Application Error Codes

To explain further why a mobile number is invalid, HLR API returns advanced status messages.

Examples

Advanced Status

GET https://app.messagehub.nl/apis/hlr/v2/{mobile}

GET https://app.messagehub.nl/apis/hlr/v2/447778547861

{
"status_code" : 200,
"status_message" : "OK",
"payload" : {
"phone" : "447778547861",
"status" : "invalid",
"advanced_status" : "ABSENT_SUBSCRIBER_SM"
}
}