REST SMS Gateway API - credits resource

This blog post has been superseded with our website documentation

credits

This document is referred to by the REST SMS Gateway API – Specification Document.
Resource URI:

http://api.textmarketer.co.uk/services/rest/credits

Actions on the account credits.

GET method – get the number of credits currently available on your account
POST method – transfer credits between accounts

GET

GET method

Get the number of credits currently available on your account.
Example usage

http://api.textmarketer.co.uk/services/rest/credits

Example GET response

<response processed_date="2010-03-19T15:19:33+00:00">
<credits>37</credits>
</response>

Read the advanced specification of this response

.
Specific error codes
N/A
Example PHP code

<?php
/**
 * GET request on the 'credits' resource
 */
$url = 'http://api.textmarketer.co.uk/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!!
$password = 'myAPIpassword'; // CHANGE THIS!!!
$url = "$url?username=$username&password=$password";
// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);
// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);
	$credits = (int) $xml_obj->credits;
	// do something with the result
	echo $credits;
} else {
	// handle the error
	var_dump($responseBody);
}
?>

POST method

Transfer credits from the source/master account to the target/sub account.
Example usage

http://api.textmarketer.co.uk/services/rest/credits

Post arguments

parameter	usage
quantity	the number of credits to transfer from the source account to the target account. Must be a positive integer.
target	the account number of the account to transfer the credits to (this can be found in the Settings > Account Settings page in the Web interface)
username	(optional) required if not using HTTP Digest authentication – this is the username of the source/master account
password	(optional) required if not using HTTP Digest authentication – this is the password of the source/master account

OR you can specify the target account user name and password, rather than the target account number

parameter	usage
quantity	the number of credits to transfer from the source account to the target account. Must be a positive integer.
target_username	this is the username of the target/sub account to transfer credits TO
target_password	this is the password of the target/sub account to transfer credits TO
username	(optional) required if not using HTTP Digest authentication – this is the username of the source/master account to transfer credits FROM
password	(optional) required if not using HTTP Digest authentication – this is the password of the source/master account to transfer credits FROM

Example POST

Example POST response

<response processed_date="2010-03-23T10:31:39+00:00">
	<source_credits_before>1000</source_credits_before>
	<source_credits_after>900</source_credits_after>
	<target_credits_before>0</target_credits_before>
	<target_credits_after>100</target_credits_after>
</response>

Read the advanced specification of this response

.
Specific error codes

Code	Meaning
0	there are insufficient credits available to transfer the specified quantity, or the specified quantity is not a positive number
1	the target account number specified is not a valid number or username/password combination does not refer to any known account

Example XML

Example XML error response

<response processed_date="2010-03-24T14:37:41+00:00">
<errors>
	<error code="0">Invalid number of credits specified: -1</error>
	<error code="1">Invalid destination account number</error>
</errors>
</response>

Example PHP code

<?php
/**
 * POST request on the 'credits' resource (credit transfer)
 */
$url = 'http://api.textmarketer.co.uk/services/rest/credits';
// uncomment for testing:
//$url = 'http://sandbox.textmarketer.biz/services/rest/credits';
$username = 'myAPIusername'; // CHANGE THIS!!! - the username of the account you're transferring FROM
$password = 'myAPIpassword'; // CHANGE THIS!!!
$targetAccountNumber = 0; // CHANGE THIS!!
$data = array('quantity'=>'1',
	'target'=>$targetAccountNumber,
	// or you could use the target username/password instead of 'target'
	// 'target_username'=>$targetUserName, 'target_password'=>$targetPassword,
	'username'=>$username, 'password'=>$password);
$data = http_build_query($data, '', '&');
// we're using the curl library to make the request
$curlHandle = curl_init();
curl_setopt($curlHandle, CURLOPT_URL, $url);
curl_setopt($curlHandle, CURLOPT_RETURNTRANSFER, true);
curl_setopt($curlHandle, CURLOPT_POSTFIELDS, $data);
curl_setopt($curlHandle, CURLOPT_POST, 1);
$responseBody = curl_exec($curlHandle);
$responseInfo  = curl_getinfo($curlHandle);
curl_close($curlHandle);
// deal with the response
if ($responseInfo['http_code']==200)
{
	$xml_obj = simplexml_load_string($responseBody);
	// do something with the result
	echo "Source account credits before: $xml_obj->source_credits_before\n";
	echo "Source account credits after: $xml_obj->source_credits_after\n";
	echo "Target account credits before: $xml_obj->target_credits_before\n";
	echo "Target account credits after: $xml_obj->target_credits_after\n";
} else {
	// handle the error here
	var_dump($responseInfo);
	var_dump($responseBody);
}
?>

REST SMS Gateway API – credits resource

credits