|
Account Query Web Services HTTP API
Using the Account Query Web Services you can programatically, and securely, query your account(s) to determine various pieces of information such as your account balance. These can be very useful when writing your own applications that leverage our messaging gateway, for example.
This document assumes you are already familiar with the HTTP Web Services 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 HTTP POST instead of GET. By doing so you will ensure you have a secure connection over which to send your account details and messages.
Available Credit
You must specify your account Username and PIN number, along with the empty AvailableCredit tag.
| Element Name | Required | Description |
|---|---|---|
| AvailableCredit | 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 |
If the Username and PIN are correct the response will include the credit on that account.
| Element Name | Required | Description |
|---|---|---|
| AvailableCredit | Required | CCC NN.NNNN where CCC is the ISO 4217 three-letter alphabetic currency code for the currency which the credit will be given in. Currently this is always GBP but may be subject to change in the future. NN.NNNN is the amount of credit, expressed as a floating point number to four decimal places, on the account. |
For example:
POST /webservices/http/queryaccount 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&AvailableCredit=
The response will be your available credit
AvailableCredit=GBP 15.2345
An incorrect Username or PIN would return
MessageIdentifier=-1&Report=2&Text=Invalid%20Login
Available Messages
You can query your approximate available premiere messages. You must include your Username and PIN to identify the account and to authenticate yourself. Note that this is the number of premier messages, not economy messages, and that the calculation of your messages is done using the current tariff you are on at that moment.
| Element Name | Required | Description |
|---|---|---|
| AvailableMessages | 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 |
If the Username and PIN are correct the response will include the messages on that account.
| Element Name | Required | Description |
|---|---|---|
| AvailableMessages | Required | The approximate number of messages, as a positive integer, that are available on the account identified by the Username and PIN. |
POST /webservices/http/queryaccount 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&AvailableMessages=
The response will be your approximate available messages
AvailableMessages=1002
An incorrect Username or PIN will return
MessageIdentifier=-1&Report=2&Text=Invalid Login
Permitted ReplyTo List
You can get a list of valid ReplyTo values for your account by using the PermittedReplyTo call with the account Username and PIN. The ReplyTo field is used when sending messages and is where the messages appear to come from when read by the recipient. If you have two-way numbers or an Originator Address configured, these will be returned by this call. These values can be used in a drop-down list, for example, in your own application/website.
| Element Name | Required | Description |
|---|---|---|
| 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 |
If the Username and PIN are correct the response will include the values you are permitted to use in the ReplyTo when sending messages.
| Element Name | Required | Description |
|---|---|---|
| PermittedReplyTo | Required | A comma separated list of ReplyTo values that this account is permitted to use. This will always include at least csoft.co.uk, which is the global default for all messages. |
POST /webservices/http/queryaccount HTTP/1.1
Host: www.csoft.co.uk:80
Content-Type: application/x-www-form-urlencoded; charset="utf-8"
Content-Length: 51
Username=ANOther.12345&PIN=123456&PermittedReplyTo=
This will produce a response which includes a comma separated list of valid values.
HTTP/1.1 200 OK
Date: Mon, 04 Apr 2005 09:23:02 GMT
Server: Apache/1.3.31 (Unix) (Doors/Red-Hat/Linux) mod_ssl/2.8.19
OpenSSL/0.9.7a PHP/4.3.10 mod_perl/1.29 mod_fastcgi/2.4.2
Transfer-Encoding: chunked
Content-Type: text/html;
PermittedReplyTo=447700912345,csoft.co.uk
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.