|
Account Management Web Services HTTP API
Using the Account Management Web Services you can programatically, 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.
These services are restricted and cannot be used without permission. Please contact us if you would like access to them.
Create Child Account
To create a child account you must supply:
| 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. |
The usual response will be the new child account login details:
| 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.1Host: 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.
| 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. |
The response will be a report code that indicates whether deletion of the child account succeeded.
| 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.1Host: 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.
| 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 |
The response will be a report code that indicates whether the transfer of succeeded.
| Report | A report code that indicates whether the transfer was successful (0) or whether something went wrong, such as an invalid login details (2). |
For example:
POST /webservices/http/manageaccount HTTP/1.1Host: 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.