Version 2.0C

Introduction

With MobiWeb 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 the HLR API, you will need a valid API account. If you don't have one yet, click here to register for a FREE account.

Authentication

https://[HOST]/apis/auth

HLR

https://[HOST]/apis/hlr/v2/

[HOST]

Replace [HOST] with your API account domain name or IP.

Authentication

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://[host]/apis/auth

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

access_token

If the request succeeded, an authentication object is returned, which includes an access_token and a refresh_token. Otherwise, an error is returned. access_token grants you access to make requests.

Setup the Authorization HTTP header with your access_token. Authorization: Bearer dcec4eb6-035c-41a4-9871-82c5bd3ef379

access_token is valid for 30 minutes, after which it expires. To preserve connection you must either refresh with refresh_token or reset connection and request a new access_token.

refresh_token

To refresh connection you must send an auth request.

https://[host]/apis/auth

This request accepts parameters type with value "refresh_token" , refresh_token with value the refresh token, provided by a previously successful auth request.

Authentication

POST https://[HOST]/apis/auth

HTTP

POST https://[HOST]/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"
		}
	}

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

	//Your account username and password
	$username = "";
	$password = "";
	
	$client = new MobiWeb\Rest\Client($username, $password);

Refresh Connection

POST https://[HOST]/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"
	 }
}

Lookup A Number

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

https://[host]/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 enforced by national telecommunication authorities and mobile operators. Otherwise, an error is returned.

Lookup A Number

GET https://[host]/apis/hlr/v2/{mobile}

HTTP

GET https://[host]/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"
 }
}

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//Your account username and password
$username = "";
$password = "";
	  
$client = new MobiWeb\Rest\Client($username, $password);

//HLR lookup for a mobile number
$lookup = $client->lookup(
	"44xxxxxxxxxx" //The mobile number in international E.164 format.
);

//Print the HLR lookup result
print_r($lookup);

Get Balance

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

https://[host]/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.

Get Balance

GET https://[host]/apis/hlr/v2/balance

HTTP

GET https://[host]/apis/sms/mt/v2/balance
Content-Type : application/json

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

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//Your account username and password
$username = "";
$password = "";
	  
$client = new MobiWeb\Rest\Client($username, $password);

//Get account balance and print it
echo $client->getBalance();

Get Pricing

To get your account’s pricing details and covered countries, you must make a pricing GET request.

https://[host]/apis/hlr/v2/pricing

Remember to setup the Authorization HTTP header with your access_token.

If the request succeeded, an object is returned, which includes your account currency and an array of country objects with coverage and pricing information. Countries have attributes country id, countrycode, country countryiso and your acount price per HLR query to this country. Otherwise, an error is returned.

Get Pricing

GET https://[host]/apis/hlr/v2/pricing

HTTP

GET https://[host]/apis/hlr/v2/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
		 {
			 "id" : 473,
			 "countryname" : "Afghanistan",
			 "countrycode" : "+93",
			 "countryiso" : "AF",
			 "price" : "0.005"
		 },
			 ..............
		 ]
	 }
}

PHP

Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk

//Your account username and password
$username = "";
$password = "";
	  
$client = new MobiWeb\Rest\Client($username, $password);

//Get account pricing and print it
print_r($client->getPricing(MobiWeb\Rest\Client::HLR));

Errors

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

HLR API returns errors in an object.

Object Attributes

code numeric

Application error code identifying error.
message string

A human-readable message providing more details about the error.

Errors

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

HTTP Status Codes

200	OK	Everything worked as expected.
401	Unauthorized	No valid API key provided.
404	Not Found	The requested resource doesn't exist.
422	Unprocessable Request	The request unprocessable, often due to invalid parameters.
500	Internal Server Error	The service is temporarily unavailable.

Application Error Codes

1001	Invalid token type	Invalid parameter.
1002	Invalid username	Invalid parameter.
1003	Invalid password	Invalid parameter.
1004	Invalid authentication credentials	Credentials provided is not correct.
1005	Invalid refresh token	Invalid parameter.
1006	Insufficient balance	User balance is not enough in order to process the request.
1007	URI not found	Request URI not found.
1009	Invalid access token	Access token is invalid.
1221	Invalid phone (MSISDN)	Invalid parameter.
1222	Service is not available	Service is temporarily unavailable.
2002	Error requesting HLR	Error requesting HLR. Please retry later.
2003	Invalid phone (MSISDN)	Invalid parameter.
2004	HLR unavailable	You account does not have permissions to use HLR service.
2005	Destination not supported	Destination network is not supported.

Advanced Status

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

Advanced Status

GET https://[host]/apis/hlr/v2/{mobile}

GET https://[host]/apis/hlr/v2/447778547861

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

Advanced Status Messages

ABSENT_SUBSCRIBER_SM	The subscriber is absent.
CALL_BARRED	The HLR is barred by the queried operator.
DATA_MISSING	The data is missing.
FACILITY_NOT_SUPPORTED	The short message facility is not supported.
HLR_ABORT	Operator’s HLR blocked the HLR request.
HLR_LOCAL_CANCEL	Operator’s HLR did not respond to the request.
HLR_REJECT	Operator’s HLR rejected the request.
SYSTEM_FAILURE	A system failure occurred.
TELE_SERVICE_NOT_PROVISIONED	The SMS teleservice is not provisioned.
TIMEOUT	HLR request received not response.
UNEXPECTED_DATA_VALUE	An unexpected data value was found in the request.
UNKNOWN_SUBSCRIBER	The subscriber is unknown.

The AUTH Request

POST

The auth request is used to authenticate and gain access to the HLR API requests.

Parameters

type required predefined string "access_token" , "refresh_token"

The type of the auth request. Can be "access_token" to reset connection or "refresh_token" to refresh connection.
username required for type "access_token" string

The username of your HLR API account.
password required for type "access_token" string

The password of your HLR API account.
refresh_token required for type "refresh_token" string

The refresh_token. Used when refreshing the connection.

Response

If the request succeeds, an authentication object is returned. An access_token for HLR API requests and a refresh_token to refresh the connection are provided. Returns an error on failure.

Object Attributes

access_token string

The access_token to use with the HLR API requests.
validity_period numeric

The validity period of access_token and refresh_token.
refresh_token string

The refresh_token to use when refreshing the connection.

/auth

POST https://[HOST]/apis/auth

POST https://[HOST]/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"
	 }
}

The /{MOBILE} Request

GET

The /{mobile} GET request is used to get validity and portability information of mobile numbers.

URL Parameters

mobile required numeric

The mobile subscriber number in international E.164 format.

Response

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 enforced by national telecommunication authorities and mobile operators. Otherwise, an error is returned.

Object Attributes

phone string

The mobile subscriber number in international E.164 format.
status predefined string "valid" , "invalid", "error"

The result status of the submitted mobile number.
advanced_status predefined string

Advanced status explanation returned when submitted mobile number is invalid. For more information, refer to Advanced Status section
mcc string

The Mobile Country Code of the operator network that the mobile number belongs to.
mnc string

The Mobile Network Code of the operator network that the mobile number belongs to.
imsi string

The IMSI (Unique identification number of subscriber). It may not be available, due to restrictions enforced by national telecommunication authorities and mobile operators. If it is not available, 0 is returned.
msc string

The MSC address of the subscriber's device. It may not be available, due to restrictions enforced by national telecommunication authorities and mobile operators. If it is not available, 0 is returned.
cost string

The cost for this HLR submission.
country string

The country of the operator network that the mobile number belongs to.
operator string

The operator network's name that the mobile number belongs to.

/{MOBILE}

GET https://[host]/apis/hlr/v2/{mobile}

GET https://[host]/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"
	 }
}

The BALANCE Request

GET

The balance GET request is used to get an account's balance.

Response

If the request succeeds, an object with the current account's balance is returned. Returns an error on failure.

Object Attributes

balance string

The balance of your account.

/balance

GET https://[host]/apis/hlr/v2/balance

GET https://[host]/apis/hlr/v2/balance
Content-Type : application/json

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

The PRICING Request

GET

The pricing GET request is used to get your account’s pricing details and covered countries.

Response

If the request succeeds, an object is returned, which includes your account currency and an array of country objects with coverage and pricing information. Returns an error on failure.

Object Attributes

currency object

currency object.
- name string
  
  The name of your account's currency.
- symbol string
  
  The symbol of your account's currency.
pricing array

Array of pricing objects.
- id numeric
  
  Country id.
- countryname string
  
  Country name.
- countrycode string
  
  Country code of country.
- countryiso string
  
  ISO code of country.
- price string
  
  Price per HLR query to this country.

/pricing

GET https://[HOST]/apis/hlr/v2/pricing

GET https://[host]/apis/hlr/v2/pricing
Content-Type : application/json

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
          {
             "id" : 473,
             "countryname" : "Afghanistan",
             "countrycode" : "+93",
             "countryiso" : "AF",
             "price" : "0.005"
           },
          ..............
		 ]
	 }
}

Examples

Version 2.0C

Introduction

Authentication

HLR

[HOST]

Authentication

access_token

refresh_token

Authentication

Refresh Connection

Lookup A Number

Lookup A Number

Get Balance

Get Balance

Get Pricing

Get Pricing

Errors

Application Errors

Object Attributes

code numeric

message string

Errors

HTTP Status Codes

Application Error Codes

Advanced Status

Advanced Status

Advanced Status Messages

The AUTH Request

Parameters

type required predefined string "access_token" , "refresh_token"

username required for type "access_token" string

password required for type "access_token" string

refresh_token required for type "refresh_token" string

Response

Object Attributes

access_token string

validity_period numeric

refresh_token string

/auth

The /{MOBILE} Request

URL Parameters

mobile required numeric

Response

Object Attributes

phone string

status predefined string "valid" , "invalid", "error"

advanced_status predefined string

mcc string

mnc string

imsi string

msc string

cost string

country string

operator string

/{MOBILE}

The BALANCE Request

Response

Object Attributes

balance string

/balance

The PRICING Request

Response

Object Attributes

currency object

name string

symbol string

pricing array

id numeric

countryname string

countrycode string

countryiso string

price string

/pricing