Account Query API - HTTP Web Service

Using the Account Query Web Services you can programmatically, 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.

Request parameters
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

Request parameters:

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.

Response parameters
Element Name Required Description
Currency Required 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.
AvailableCredit Required NN.NNNN is the amount of credit, expressed as a floating point number to four decimal places, on the account.

Response parameters:

Currency (required)
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.
AvailableCredit (required)
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.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&AvailableCredit=

The response format is a tag=value style that is more appropriate for parsing, which will contain your available credit:

Currency=GBP&AvailableCredit=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.

Request parameters
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

Request parameters:

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.

Response parameters
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.

Response parameters:

AvailableMessages (required)
The approximate number of messages, as a positive integer, that are available on the account identified by the Username and PIN.

For example:

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 (Sender ID) List

You can get a list of valid ReplyTo (Sender ID) 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.

Request parameters
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

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

If the Username and PIN are correct the response will include the values you are permitted to use in the ReplyTo when sending messages.

Response parameters
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.

Response parameters:

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.

For example:

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.

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