Version 2.1C

Introduction

With MobiWeb SMS API you can send SMS messages to 7+ billion subscribers of 1000+ Mobile Operators in 200+ countries.

The SMS 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 SMS 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

SMS

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

Send Single SMS

To send an sms you must send a send POST request.

https://[host]/apis/sms/mt/v2/send

Set parameters to with the the recipient mobile number phone in international E.164 format and from with your preferred sender.

Finally, setup parameter message with your message text.

Remember to setup the Authorization HTTP header with your access_token.

Congratulations! You just sent your first SMS using the SMS API.

If the request succeeded, an object is returned, which includes submission status, message id, type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

Send Single SMS

POST https://[host]/apis/sms/mt/v2/send
 
POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json

[
	{
		 "to" : ["447945223343"],
		 "from" : "HelloWorld",
		 "message" : "My first SMS message."
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521789981,
			 "to" : "447945223343",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		}
	 ]
}
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);
//Submit message
$message = $client->broadcast(
	[[
		"from" => "HelloWorld", //The sender displayed upon the SMS arrival. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
		"to" => ["44xxxxxxxxxx"], //The full international number(s) of the recipient(s) in international E.164 format https://en.wikipedia.org/wiki/E.164.
		"message" => "Hello from MobiWeb!" //The text of the SMS message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_/_GSM_03.38, you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table https://en.wikipedia.org/wiki/UTF-16, because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.
	]]
);

//Print message
print_r($message);

All Options

//Your account username and password
$username = "";
$password = "";

$client = new MobiWeb\Rest\Client($username, $password);
//Submit message
$message = $client->broadcast(
	[[
		"from" => "HELLO", //The sender displayed upon the SMS arrival. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
		"to" => ["44xxxxxxxxxx"], //The full international number(s) of the recipient(s) in international E.164 format https://en.wikipedia.org/wiki/E.164.
		"message" => "Hello from MobiWeb!" //The text of the SMS message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_/_GSM_03.38, you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table https://en.wikipedia.org/wiki/UTF-16, because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.
		"options" => [
			"receive_dlr" => "1", //Set this parameter to ‘1’ for requesting delivery report for this SMS. Refer to receive Delivery Reports section for more information . https://api.solutions4mobiles.com/sms-api.html#receive_delivery_reports
			"message_type" => "sms", //The type of the SMS message.
			"track_url" => "0", //Set this parameter to ‘1’ to shorten and track URL link for this SMS. Refer to receive URL tracking and conversion section for more information . https://api.solutions4mobiles.com/sms-api.html#receive_url_ctr
			"reference_code" => "ABCD1234", //Set this parameter to your preferred reference id / custom data for this submission. Length can be up to 50 characters.
			"schedule_date" => "2021-06-16 13:06:00", //Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to schedule your sending to a future datetime. Must be at least 20 minutes from now.
			"expire_date" => "2021-06-16 15:00:00" //Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to force expiration of your SMS to a future datetime. Must be at least 30 minutes from now and schedule_date.
		]
	]]
);

//Print message
print_r($message);

Multilingual Support

POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json
[
	{
		 "to" : ["8613054782931"],
		 "from" : "HELLO",
		 "message" : "早上好我的朋友"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521789982,
			 "to" : "8613054782931",
			 "from" : "HELLO",
			 "message" : "早上好我的朋友",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		}
	 ]
}
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);
//Submit message
$message = $client->broadcast(
	[[
		"from" => "HELLO", //The sender displayed upon the SMS arrival. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.
		"to" => ["44xxxxxxxxxx"], //The full international number(s) of the recipient(s) in international E.164 format https://en.wikipedia.org/wiki/E.164.
		"message" => "早上好我的朋友" //The text of the SMS message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table https://en.wikipedia.org/wiki/GSM_03.38#GSM_7-bit_default_alphabet_and_extension_table_of_3GPP_TS_23.038_/_GSM_03.38, you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table https://en.wikipedia.org/wiki/UTF-16, because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.
	]]
);

//Print message
print_r($message);

Send Multiple SMS

To send multiple sms you must send a send POST request.

https://[host]/apis/sms/mt/v2/send

Set parameters message with your message text and from with your preferred sender.

Now, set parameter to with an array of the recipient mobile numbers in international E.164 format.

In this request, body is enclosed in an array. Repeat adding objects to send SMS with different messages and/or senders to multiple recipients.

Remember to setup the Authorization HTTP header with your access_token.

Congratulations! You just sent multiple SMS using one request.

If the request succeeded, a response object is returned, which includes id, broadcast_date, expiration_date and the cost of the sms. Otherwise, an error is returned.

Send Multiple SMS

POST https://[host]/apis/sms/mt/v2/send
 
POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json

[
	{
		 "to" : ["447945223343"],
		 "from" : "OTP PIN",
		 "message" : "Your one time pin is: 875529"
	},
	{
		 "to" : ["447945223342","447945223341"],
		 "from" : "Alert",
		 "message" : "A product in your watchlist is on discount. For more information click here: http://bit.ly/1jL3YEw"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521789995,
			 "to" : "447945223343",
			 "from" : "OTP PIN",
			 "message" : "Your one time pin is: 875529",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		},
		{
			 "status" : "submitted",
			 "id" : 543521789996,
			 "to" : "447945223342",
			 "from" : "Alert",
			 "message" : "A product in your watchlist is on discount. For more information click here: http://bit.ly/1jL3YEw",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		},
		{
			 "status" : "submitted",
			 "id" : 543521789997,
			 "to" : "447945223341",
			 "from" : "Alert",
			 "message" : "A product in your watchlist is on discount. For more information click here: http://bit.ly/1jL3YEw",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		}
	 ]
}
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);
//Submit messages
$message = $client->broadcast(
	[[
		"from" => "OTP PIN",
		"to" => ["44xxxxxxxxxx"],
		"message" => "Your one time pin is: 875529"
	],
	[
		"from" => "Alert",
		"to" => ["44xxxxxxxxxx","44xxxxxxxxxx"],
		"message" => "A product in your watchlist is on discount."
	]]
);

//Print messages
print_r($message);

Send WAP Push

To send a WAP Push you must send a send POST request.

https://[host]/apis/sms/mt/v2/send

Set parameters to with the the recipient mobile number phone in international E.164 format and from with your preferred sender.

Setup parameter wap_title with your preferred title.

Setup parameter wap_url to your resource URI (image / document /video etc) location.

Finally, setup message_type with value "wap_push".

Remember to setup the Authorization HTTP header with your access_token.

Congratulations! You just sent a WAP Push using the SMS API.

If the request succeeded, an object is returned, which includes submission status, message id, type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

Send WAP Push

POST https://[host]/apis/sms/mt/v2/send
 
POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json

[
	{
		 "to" : ["447945223343"],
		 "from" : "Purchase",
		 "wap_title" : "Your purchase link",
		 "wap_url" : "http://bit.ly/1Rmmw1b",
		 "message_type" : "wap_push"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521790030,
			 "to" : "447945223343",
			 "from" : "Purchase",
			 "wap_title" : "Your purchase link",
			 "wap_url" : "http://bit.ly/1Rmmw1b",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		}
	 ]
}

Send Flash SMS

To send a flash you must send a send POST request.

https://[host]/apis/sms/mt/v2/send

Set parameters to with the the recipient mobile number phone in international E.164 format and from with your preferred sender.

Setup parameter message with your message text.

Finally, setup message_type with value "flash".

Remember to setup the Authorization HTTP header with your access_token.

Congratulations! You just sent a flash SMS using the SMS API.

If the request succeeded, an object is returned, which includes submission status, message id, type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

Send Flash SMS

POST https://[host]/apis/sms/mt/v2/send
 
POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json

[
	{
		 "to" : ["447945223343"],
		 "from" : "HelloWorld",
		 "message" : "My first SMS message.",
		 "message_type" : "flash"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521789981,
			 "to" : "447945223343",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		}
	 ]
}

URL Tracking And Shortening

You can track URL links conversion contained in SMS messages.

As soon as a user clicks a link, CTR, platform, operating system, browser, mobile number and network information is forwarded automatically, to your system / platform.

Setup parameter track_url with value "1".

Remember to setup the Authorization HTTP header with your access_token.

Congratulations! Our system will automatically shorten and setup tracking for URL.

If the request succeeded, an object is returned, which includes submission status, message id, type of message and the initial cost of the sms message. (Notice: the initial cost is calculated based on the prefix of the recipient's number. Final cost is calculated when the SMS is sent by the platform, where more advanced identification processes are used ) Otherwise, an error is returned.

URL Tracking And Shortening

POST https://[host]/apis/sms/mt/v2/send
 
POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json

[
	{
		 "to" : ["447945223343"],
		 "from" : "ShopTop",
		 "message" : "20% off purchases made today: http://www.eshoptopcommerce.com/store/products/SDi9jdq0dhq0.html",
		 "track_url" : 1,
		 "message_type" : "sms"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521790030,
			 "to" : "447945223343",
			 "from" : "ShopTop",
			 "message" : "20% off purchases made today: p7m.me/DF65t4s1",
			 "track_url" : 1,
			 "url" : "http://www.eshoptopcommerce.com/store/products/SDi9jdq0dhq0.html",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		}
	 ]
}

Receive Delivery Reports

Delivery reports are forwarded automatically, to the user system / platform. When an SMS delivery report is received by our SMS API Platform, the DLR information is immediately forwarded to your specified DLR Callback URL via a POST request. Data are transmitted in JSON format.

You can setup your DLR Callback URL in the web portal

https://[DLR Callback URL]

DLR forwarding POST request transmits the message id ( cross-check with message id returned from send POST requests ), recipient phone, delivery status, delivery date, final cost, network operator id of the recipient phone and reference id / custom data of the message submission. Otherwise, an error is returned.

SMS API Platform will stop sending DLR information of a SMS when it accepts a HTTP Status Code 200 from the user’s system. HTTP Status Code 200 is considered as a valid acknowledgement of DLR information from the user side.

SMS API Platform will send out DLR based on the following schedule:

DLR Forwarding Schedule

  • 1st Attempt

    instantly

  • 2nd Attempt

    after 5 minutes

  • 3rd Attempt

    after 15 minutes

  • 4th Attempt

    after 30 minutes

  • 5th Attempt

    after 1 hour

  • 6th Attempt

    after 5 hours

  • 7th Attempt

    after 24 hours

At this point, if the user system still fails to acknowledge DLR information, there will be no more attempts to transmit and information will be discarded.

There are multiple delivery status codes:

Delivery Status Codes

  • 0

    No Status

  • 1

    Delivered

  • 2

    Failed / Erroneous Number

  • 3

    Failed / Network Error

  • 4

    Pending

  • 5

    Expired

Receive Delivery Reports

POST https://[DLR Callback URL]
Content-Type : application/json

{
	 "id" : 543521789981,
	 "phone" : "447945223343",
	 "status" : 1,
	 "date" : "2014-09-02 09:37:31",
	 "cost" : "0.067",
	 "operator_id" : 473,
	 "reference_code" : "FH832JR0REW1F0"
}

HTTP/1.1 200 OK
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//For information about receiving delivery reports please visit https://api.solutions4mobiles.com/sms-api.html#receive_delivery_reports

//Get request
$inputJSON = file_get_contents('php://input');

//convert JSON into array
$input = json_decode($inputJSON, TRUE);

//Print data
print_r($input);

//Return successful http code
header('HTTP/1.1 200 OK', TRUE, 200);
//or error
//header('HTTP/1.1 500 Internal Server Error', true, 500);

Receive URL Tracking And Conversion Information

URL tracking information is forwarded automatically, to the user system / platform. When a user clicks a link, the CTR and user information is immediately forwarded to your specified Callback URL via a POST request. Data are transmitted in JSON format.

You can setup your Callback URL in the web portal

https://[DLR Callback URL]

URL Tracking POST request transmits the message id ( cross-check with message id returned from send POST requests ), recipient phone, url open date, the url tracked, user_agent (includes platform, device, operating system, browser etc.), message information and network operator information. Otherwise, an error is returned.

SMS API Platform will stop sending URL tracking information of a SMS when it accepts a HTTP Status Code 200 from the user’s system. HTTP Status Code 200 is considered as a valid acknowledgement of URL information from the user side.

SMS API Platform will send out URL tracking information based on the following schedule:

URL Tracking Information Schedule

  • 1st Attempt

    instantly

  • 2nd Attempt

    after 5 minutes

  • 3rd Attempt

    after 15 minutes

  • 4th Attempt

    after 30 minutes

  • 5th Attempt

    after 1 hour

  • 6th Attempt

    after 5 hours

  • 7th Attempt

    after 24 hours

At this point, if the user system still fails to acknowledge URL information, there will be no more attempts to transmit and information will be discarded.

URL Tracking Information

POST https://[Callback URL]
Content-Type : application/json

{
	 "id" : 543521789981,
	 "phone" : "447945223343",
	 "url" : "http://www.eshoptopcommerce.com/store/products/SDi9jdq0dhq0.html",
	 "user_agent" : "Mozilla/5.0 (iPhone; CPU iPhone OS 9_1 like Mac OS X) AppleWebKit/601.1.46 (KHTML, like Gecko) Version/9.0 Mobile/13B143 Safari/601.1",
	 "date" : "2015-10-12 13:21:12",
	 "sender" : "ShopTop",
	 "message" : "20% off purchases made today: p7m.me/DF65t4s1",
	 "operator" : "T-Mobile UK",
	 "mcc" : "234",
	 "mnc" : "30"
}

HTTP/1.1 200 OK
Download source here
OR
with composer RUN from command-line composer require mobiweb/sdk 
//For information about receiving url tracking and conversion information please visit https://api.solutions4mobiles.com/sms-api.html#receive_url_ctr

//Get request
$inputJSON = file_get_contents('php://input');

//convert JSON into array
$input = json_decode($inputJSON, TRUE);

//Print data
print_r($input);

//Return successful http code
header('HTTP/1.1 200 OK', TRUE, 200);
//or error
//header('HTTP/1.1 500 Internal Server Error', true, 500);

Get Balance

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

https://[host]/apis/sms/mt/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/sms/mt/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 networks, you must make a pricing GET request.

https://[host]/apis/sms/mt/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 network objects with coverage and pricing information. Network objects have attributes operator id, operator countryname, operatorname, operator mobile country code mcc, operator mobile network code mnc and your acount price per SMS sent to this network. Otherwise, an error is returned.

Get Pricing

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

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
		 {
			 "id" : 473,
			 "countryname" : "Afghanistan",
			 "operatorname" : "Roshan",
			 "mcc" : "412",
			 "mnc" : "020",
			 "price" : "0.0190"
		 },
			 ..............
		 ]
	 }
}
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::SMS));

Errors

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

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

Application Errors

SMS API returns errors in an array of objects.

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.
400 Bad Request The request was unacceptable, often due to invalid JSON format.
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.
1101 Invalid JSON format Invalid JSON structure.
1200 Invalid parameter (from) Invalid parameter. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-) or 14 numeric characters (0-9). Special characters are not allowed.
1201 Invalid Parameters List Parameter list is malformed.
1202 Invalid message Invalid parameter.
1203 Invalid parameter (to) Invalid parameter.
1204 SMS unavailable You account does not have permissions to use SMS service.
1205 Invalid receive_dlr Invalid parameter.
1206 Invalid message_type Invalid parameter.
1207 Invalid wap_title Invalid parameter.
1208 Invalid track_url Invalid parameter.
1209 Invalid wap_url Invalid parameter.
1213 Invalid udd Invalid parameter.
1214 Invalid udh Invalid parameter.
1215 Invalid schedule_date Invalid parameter.
1216 Invalid schedule_date schedule_date must be at least 20 minutes from now.
1217 Invalid expire_date Invalid parameter.
1218 Invalid expire_date expire_date must be 30 minutes from schedule_date.
1219 Invalid expire_date expire_date must be 30 minutes from now.
1221 Invalid phone (MSISDN) Invalid parameter.
1222 Service is not available Service is temporarily unavailable.
1223 Error submitting SMS Service is temporarily unavailable.

The AUTH Request

POST

The auth request is used to authenticate and gain access to the SMS 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 SMS API account.

  • password required for type "access_token" string

    The password of your SMS 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 SMS 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 SMS 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 SEND Request

POST

The send request is used to send a single or multiple SMS messages.

Request

The request body must be an array of objects, each one representing an SMS with one or multiple recipients.

Parameters

  • to required array

    The full international number(s) of the recipient(s) in international E.164 format.

  • from required string

    The sender displayed upon the SMS arrival. Can be composed of 2-11 alphanumeric characters (A-z,0-9, ,-,.) or 14 numeric characters (0-9). Special characters are not allowed.

  • message_type optional (Default "sms") predefined string "sms" , "flash" , "wap_push" , "binary"

    The type of the SMS message.

  • message required for "sms" , "flash" string

    The text of the SMS message. If all characters in the message belong to the 3GPP GSM 7-bit GSM 03.38 ASCII character table, you can send up to 160 characters in a single SMS. You can send longer messages automatically by setting message parameter with your preffered text. In long SMS (multi-part SMS), each SMS part can be up to 153 characters. Each part costs as 1 SMS. If one or more characters in the message belong to the 16-bit Unicode / UCS-2 character table, because of the increased memory requirement for each character, you can send up to 70 characters in a single SMS. In long SMS (multi-part SMS), each SMS part can be up to 67 characters. Each part costs as 1 SMS.

  • receive_dlr optional (Default 1) predefined numeric 0 , 1

    Set this parameter to ‘1’ for requesting delivery report for this SMS. Refer to receive Delivery Reports section for more information .

  • track_url optional (Default 0) predefined numeric 0 , 1

    Set this parameter to ‘1’ to shorten and track URL link for this SMS. Refer to receive URL tracking and conversion section for more information .

  • schedule_date optional (Default NOW) date

    Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to schedule your sending to a future datetime. Must be at least 20 minutes from now.

  • expire_date optional date

    Set this parameter in format "yyyy-mm-dd hh:mm:ss" UTC +0 to force expiration of your SMS to a future datetime. Must be at least 30 minutes from now and schedule_date.

  • wap_url required for message_type "wap_push" string

    The url of a valid resource (image / document /video etc).

  • wap_title required for message_type "wap_push" string

    The title of the WAP Push link.

  • reference_code optional string

    Set this parameter to your preferred reference id / custom data for this submission. Length can be up to 50 characters.

  • udh required for message_type "binary" string

    User Data Header.

  • udd required for message_type "binary" string

    Message Data.

Response

If the request succeeds, an array of objects is returned. One object is returned per one to (recipient). Returns an error on failure.

Respone object attributes vary, depending on the message_type of the SMS submission.

Object Attributes :: sms / flash

  • status predefined string "submitted" , "error"

    The result status of SMS submission.

  • id numeric

    The SMS message id.

  • to numeric

    The recipient's phone number in international E.164 format.

  • from string

    The sender to display upon the SMS arrival.

  • message_type predefined string "sms" , "flash" , "wap_push" , "binary"

    The message type of the SMS.

  • message string

    The SMS message text.

  • schedule_date date

    The future date that the system will send the SMS.

  • expire_date date

    The date that the SMS will expire and will not be sent, in case of a queue / delay.

  • receive_dlr numeric 0 , 1

    Indicates if a DLR was requested for this submission.

  • track_url numeric 0 , 1

    Indicates if URL shorten and track was requested for this submission.

  • reference_code string

    The reference id / custom data for this submission.

  • operator_id numeric

    The mobile network operator id of the recipient phone.

  • cost string

    The cost for this SMS submission.

Object Attributes :: wap_push

  • status predefined string "submitted" , "error"

    The result status of SMS submission.

  • id numeric

    The SMS message id.

  • to numeric

    The recipient's phone number in international E.164 format.

  • from string

    The sender to display upon the SMS arrival.

  • message_type predefined string "sms" , "flash" , "wap_push" , "binary"

    The message type of the SMS.

  • wap_url string

    The url of the resource (image / document /video etc).

  • wap_title string

    The title of the WAP Push link.

  • schedule_date date

    The future date that the system will send the SMS.

  • expire_date date

    The date that the SMS will expire and will not be sent, in case of a queue / delay.

  • receive_dlr numeric 0 , 1

    Indicates if a DLR was requested for this submission.

  • operator_id numeric

    The mobile network operator id of the recipient phone.

  • cost string

    The cost for this SMS submission.

Object Attributes :: binary

  • status predefined string "submitted" , "error"

    The result status of SMS submission.

  • id numeric

    The SMS message id.

  • to numeric

    The recipient's phone number in international E.164 format.

  • from string

    The sender to display upon the SMS arrival.

  • message_type predefined string "sms" , "flash" , "wap_push" , "binary"

    The message type of the SMS.

  • udh string

    The User Data Header, in hexadecimal format.

  • udd string

    The User Data, in hexadecimal format.

  • schedule_date date

    The future date that the system will send the SMS.

  • expire_date date

    The date that the SMS will expire and will not be sent, in case of a queue / delay.

  • receive_dlr numeric 0 , 1

    Indicates if a DLR was requested for this submission.

  • operator_id numeric

    The mobile network operator id of the recipient phone.

  • cost string

    The cost for this SMS submission.

/send


Send SMS

POST https://[host]/apis/sms/mt/v2/send
 
POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json

[
	{
		 "to" : ["447945223343","447945223342","447945223341"],
		 "from" : "HelloWorld",
		 "message" : "My first SMS message.",
		 "receive_dlr" : 1,
		 "message_type" : "sms",
		 "schedule_date" : "2015-05-12 13:30:00",
		 "expire_date" : "2015-05-12 14:30:00",
		 "reference_code" : "FH832JR0REW1F0"
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521789981,
			 "to" : "447945223343",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "receive_dlr" : 1,
			 "message_type" : "sms",
			 "schedule_date" : "2015-05-12 13:30:00",
			 "expire_date" : "2015-05-12 14:30:00",
			 "reference_code" : "FH832JR0REW1F0",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		},
		{
			 "status" : "submitted",
			 "id" : 543521789984,
			 "to" : "447945223342",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "receive_dlr" : 1,
			 "message_type" : "sms",
			 "schedule_date" : "2015-05-12 13:30:00",
			 "expire_date" : "2015-05-12 14:30:00",
			 "reference_code" : "FH832JR0REW1F0",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		},
		{
			 "status" : "submitted",
			 "id" : 543521789986,
			 "to" : "447945223341",
			 "from" : "HelloWorld",
			 "message" : "My first SMS message.",
			 "receive_dlr" : 1,
			 "message_type" : "sms",
			 "schedule_date" : "2015-05-12 13:30:00",
			 "expire_date" : "2015-05-12 14:30:00",
			 "reference_code" : "FH832JR0REW1F0",
			 "operator_id" : 765,
			 "cost" : "0.0400"
		}
	 ]
}

Send Long / Multipart SMS

POST https://[host]/apis/sms/mt/v2/send
Content-Type : application/json
[
	{
		 "to" : ["447945223341"],
		 "from" : "Long SMS",
		 "message" : "Le Lorem Ipsum est simplement du faux texte employé dans la composition et la mise en page avant impression. Le Lorem Ipsum est le faux texte standard de l'imprimerie depuis les années 1500, quand un peintre anonyme assembla ensemble des morceaux de texte pour réaliser un livre spécimen de polices de texte. Il n'a pas fait que survivre cinq siècles, mais s'est aussi adapté à la bureautique informatique, sans que son contenu n'en soit modifié. Il a été popularisé dans les années 1960 grâce à la vente de feuilles Letraset contenant des passages du Lorem Ipsum."
	}
]

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : [
		{
			 "status" : "submitted",
			 "id" : 543521790022,
			 "to" : "447945223341",
			 "from" : "Long SMS",
			 "message" : "Le Lorem Ipsum est simplement du faux texte employé dans la composition et la mise en page avant impression. Le Lorem Ipsum est le faux texte standard de l'imprimerie depuis les années 1500, quand un peintre anonyme assembla ensemble des morceaux de texte pour réaliser un livre spécimen de polices de texte. Il n'a pas fait que survivre cinq siècles, mais s'est aussi adapté à la bureautique informatique, sans que son contenu n'en soit modifié. Il a été popularisé dans les années 1960 grâce à la vente de feuilles Letraset contenant des passages du Lorem Ipsum.",
			 "receive_dlr" : 1,
			 "message_type" : "sms",
			 "operator_id" : 765,
			 "cost" : "0.3200"
		}
	 ]
}

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/sms/mt/v2/balance
 
GET https://[host]/apis/sms/mt/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 networks.

Response

If the request succeeds, an object is returned, which includes your account currency and an array of network objects with coverage and pricing information. For an operator with multiple MNCs, a separate record will be displayed for each one. 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

      Mobile network operator id.

    • countryname string

      Mobile network operator country.

    • operatorname string

      Mobile network operator name.

    • mcc string

      Mobile country code of mobile operator.

    • mnc string

      Mobile network code of mobile operator.

    • price string

      Price per SMS for this mobile operator.

/pricing

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

{
	 "status_code" : 200,
	 "status_message" : "OK",
	 "payload" : {
		 "currency" : {
			 "name" : "Euro",
			 "symbol" : "EUR"
		 },
		 "pricing" : [
          {
             "id" : 473,
             "countryname" : "Afghanistan",
             "operatorname" : "Roshan",
             "mcc" : "412",
             "mnc" : "020",
             "price" : "0.0190"
          },
          ..............
		 ]
	 }
}