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
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"
		}
	}
							
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}
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"
 }
}
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
GET https://[host]/apis/sms/mt/v2/balance
Content-Type : application/json
{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "balance" : "7845.3500"
	 }
}
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
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"
		 },
			 ..............
		 ]
	 }
}
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"
           },
          ..............
		 ]
	 }
}