Account Management API - HTTP Web Service

Using the Account Management Web Services you can programmatically, and securely, manage your parent and child accounts.

This document assumes you are already familiar with the SMS Messaging Web Services HTTP API and how to use it. If you have not read this, please do so prior to trying to use these services.

We strongly urge you to use HTTPS when connecting to our servers and to use POST instead of GET. By doing so you will ensure you have a secure connection over which to send your account details and messages.

This API is currently restricted and cannot be used without prior permission. Please contact us if you would like to use this API.

Create Child Account

To create a child account you must supply:

Request parameters
Parameter Required Description
Username Required The Username for the parent account. A case-sensitive alphanumeric string with a maximum size of 20 characters e.g. ANOther.61234
PIN Required The PIN for the parent account. A case-sensitive alphanumeric string with a maximum size of 20 characters e.g. 123456
CreateChildAccountType Required The type of child account to create. This must be either TRANSFER or SHARED.
Transfer accounts cannot purchase messages or credit. Credit is transferred from the parent account to the child account (see Transfer Funds below).
Shared accounts cannot purchase messages or credit either but credit is shared with the parent account.
CreateChildAccountEmail Required The email address to associate with the account. This will be used to communicate with the account holder if necessary (for example, when out of credit).
CreateChildAccountTelephoneCountryCode Required The full international telephone country code with no plus prefix for the country where the account holder resides. For example the United Kingdom is 44, the United States is 1.
CreateChildAccountMobileNumber Required The mobile number to associate with the account in full international standard including country code. For example 4400912345.
CreateChildAccountGivenName Optional The given/first name to associate with the new child account.
CreateChildAccountFamilyName Optional The family/given name to associate with the new child account.
CreateChildAccountCompanyName Optional The company name to associate with the new child account.

Request parameters:

PermittedReplyTo (required)
Operation request element
Username (required)
The Username for the account you are querying. A case-sensitive alphanumeric string with a maximum size of 20 characters e.g. ANOther.61234
PIN (required)
The PIN for the account you are querying. A case-sensitive alphanumeric string with a maximum size of 20 characters e.g. 123456
CreateChildAccountType (required)
The type of child account to create. This must be either TRANSFER or SHARED. Transfer accounts cannot purchase messages or credit. Credit is transferred from the parent account to the child account (see Transfer Funds below). Shared accounts cannot purchase messages or credit either but credit is shared with the parent account.
CreateChildAccountEmail (required)
The email address to associate with the account. This will be used to communicate with the account holder if necessary (for example, when out of credit).
CreateChildAccountTelephoneCountryCode (required)
The full international telephone country code with no plus prefix for the country where the account holder resides. For example the United Kingdom is 44, the United States is 1
CreateChildAccountMobileNumber (required)
The mobile number to associate with the account in full international standard including country code. For example 4400912345
CreateChildAccountGivenName (optional)
The given/first name to associate with the new child account.
CreateChildAccountFamilyName (optional)
The family/given name to associate with the new child account.
CreateChildAccountCompanyName (optional)
The company name to associate with the new child account.

The usual response will be the new child account login details:

Response parameters
Parameter Description
Report A report code that indicates whether the transfer was successful (0) or whether something went wrong, such as an invalid login details (2).
Username The unique username for the new child account.
PIN The unique PIN for the new child account.

Response parameters:

Report
A report code that indicates whether the transfer was successful (0) or whether something went wrong, such as an invalid login details (2).
Username
The unique username for the new child account.
PIN
The unique PIN for the new child account.

For example:

POST /webservices/http/manageaccount HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 64

Username=ANOther.12345&PIN=123456&CreateChildAccountType=TRANSFER&CreateChildAccountEmail=another@csoft.co.uk&CreateChildAccountTelephoneCountryCode=44&CreateChildAccountMobileNumber=4477009124345

The response will be the child account login details (Username and PIN).

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2002 09:31:42 GMT
Server: Apache/1.3.22 (Unix) (Red-Hat/Linux) mod_ssl/2.8.5 OpenSSL/0.9.6b DAV/1.0.2 PHP/4.0.6 mod_perl/1.24_01 mod_fastcgi/2.2.10
Content-Length: 45
Content-Type: text/html; charset=utf-8

Report=0&Username=Another.112233&PIN=123456789

An incorrect Username or PIN would return a result like this:

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2002 09:31:42 GMT
Server: Apache/1.3.22 (Unix) (Red-Hat/Linux) mod_ssl/2.8.5 OpenSSL/0.9.6b DAV/1.0.2 PHP/4.0.6 mod_perl/1.24_01 mod_fastcgi/2.2.10
Content-Length: 45
Content-Type: text/html; charset=utf-8
   
Report=2&Text=Invalid%20Login

Delete Child Account

To delete a child account you must be the parent and know the child account Username.

Request parameters
Parameter Required Description
Username Required The unique username for this account. This is case sensitive.
PIN Required The unique PIN for this account. This is case sensitive.
DeleteChildAccountUsername Required The Username for the child account to delete.

Request parameters:

Username (required)
The unique username for this account. This is case sensitive.
PIN (required)
The unique PIN for this account. This is case sensitive.
DeleteChildAccountUsername (required)
The Username for the child account to delete.

The response will be a report code that indicates whether deletion of the child account succeeded.

Response parameters
Parameter Description
Report A report code that indicates whether deletion of the child account was successful (0) or whether something went wrong, such as an invalid login (2).

Response parameters:

Report
A report code that indicates whether deletion of the child account was successful (0) or whether something went wrong, such as an invalid login (2).

For example:

POST /webservices/http/manageaccount HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 64

Username=ANOther.12345&PIN=123456&DeleteChildAccountUsername=AChild.12345

A successful response would look like:

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2002 09:31:42 GMT
Server: Apache/1.3.22 (Unix) (Red-Hat/Linux) mod_ssl/2.8.5 OpenSSL/0.9.6b DAV/1.0.2 PHP/4.0.6 mod_perl/1.24_01 mod_fastcgi/2.2.10
Content-Length: 45
Content-Type: text/html; charset=utf-8

Report=0

Transfer Funds

You can transfer funds between your parent account and any of it's child accounts or vice-versa. You must know the account details of both accounts, however.

Request parameters
Parameter Required Description
Username Required The unique username for this account. This is case sensitive.
PIN Required The unique PIN for this account. This is case sensitive.
TransferToAccountUsername Required The Username for the target account - a case-sensitive alphanumeric string with a maximum size of 20 characters e.g. ANOther.61234
TransferCurrencyAmount Either A currency formatted amount to transfer, in pounds and pence (GBP). e.g. 10.00
TransferMessagesAmount Either An integer amount to transfer, in terms of messages. e.g. 10

Request parameters:

Username (required)
The unique username for this account. This is case sensitive.
PIN (required)
The unique PIN for this account. This is case sensitive.
TransferToAccountUsername (required)
The Username for the target account - a case-sensitive alphanumeric string with a maximum size of 20 characters e.g. ANOther.61234
TransferCurrencyAmount (either)
A currency formatted amount to transfer, in pounds and pence (GBP). e.g. 10.00
TransferMessagesAmount (either)
An integer amount to transfer, in terms of messages. e.g. 10

The response will be a report code that indicates whether the transfer of succeeded.

Response parameters
Parameter Description
Report A report code that indicates whether the transfer was successful (0) or whether something went wrong, such as an invalid login details (2).

Response parameters:

Report
A report code that indicates whether deletion of the child account was successful (0) or whether something went wrong, such as an invalid login (2).

For example:

POST /webservices/http/manageaccount HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 64

Username=ANOther.12345&PIN=123456&TransferToAccountUsername=AChild.12345&TransferCurrencyAmount=10.00

The response will contain a report code that indicates whether the transfer was successful (0) or whether something went wrong, such as an invalid login (2).

HTTP/1.1 200 OK
Date: Wed, 03 Jul 2002 09:31:42 GMT
Server: Apache/1.3.22 (Unix) (Red-Hat/Linux) mod_ssl/2.8.5 OpenSSL/0.9.6b DAV/1.0.2 PHP/4.0.6 mod_perl/1.24_01 mod_fastcgi/2.2.10
Content-Length: 45
Content-Type: text/html; charset=utf-8

Report=0

Dealing with Errors

  • If you are unable to establish a TCP/IP connection with www.csoft.co.uk then it is vital that you automatically failover to www2.csoft.co.uk.
  • If you receive a response code indicating an error condition DO NOT automatically retry your request. For example if you are Out of Credit you will still be Out Credit. If you do enter a retry loop we may block your IP address as repeated retries may appear to us to be a Denial of Service attack.

Your session is about to expire

You will be logged out in seconds.

Do you want to stay signed in?

Yes, keep me signed in     No, Sign me out