Account Query API - SOAP 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 Sending SMS Web Services SOAP 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. By doing so you will ensure you have a secure connection over which to send your account details and messages.

To aid readability in the element tables below, a + prefix indicates a complex type or operation request/response, while the indenting and - prefix indicates an element in the sequence of elements that form part of that complex type/operation. The + and - are not part of the element names, however.

Servers, Security & Failover

We have multiple servers, two of which are available for public use with this API, so that in the event of an failure you should still be able to connect to us. At least one of these servers should always be available and for maximum reliability we strongly urge you to write your application to failover to the secondary server should the primary not be available for any reason.

We support both HTTP and HTTPS protocols but we strongly urge you to use HTTPS for greater security of your account information.

The SOAP API will authenticate you using your account Username and PIN (not Password). These will have been sent to you when you signed up.

SOAP Servers
Primary http(s)://www.csoft.co.uk/sendsms5
Secondary http(s)://www2.csoft.co.uk/sendsms5

SOAP Servers

Primary
http(s)://www.csoft.co.uk/sendsms5
Secondary
http(s)://www2.csoft.co.uk/sendsms5

Available Credit

You can check the currently available credit on any of your accounts using the Username and PIN of that account with the AvailableCredit call.

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
+AvailableCreditResponse Required Operation response element
  -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.
  -Credit Required The amount of credit, expressed as a floating point number to four decimal places, on the account.
  -Reserved Ignore This section should be ignored; it is reserved for use by Connection Software.

Response parameters

+AvailableCreditResponse (required)
Operation response element
  -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.
  -Credit (required)
The amount of credit, expressed as a floating point number to four decimal places, on the account.
  -Reserved (ignored)
This section should be ignored; it is reserved for use by Connection Software.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
    xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body>
<ns2:AvailableCredit>
<Username>ANother.123456</Username>
<PIN>123456789</PIN>
</ns2:AvailableCredit>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If the Username and PIN are correct, the response will be your available credit. Note the reserved section which should be ignored. This is reserved for use by Connection Software.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
	xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
	xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body>
<ns2:AvailableCreditResponse>
<Currency>GBP</Currency>
<Credit>2.8950</Credit>
<Reserved><Field1/><Field2/><Field3/><Field4/></Reserved>
</ns2:AvailableCreditResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Available Messages

You can also check your approximate available messages using the AvailableMessages call. 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 be the approximate number of premier messages on that account.

Response parameters
Element Name Required Description
+AvailableMessagesResponse Required Operation response element
  -Messages Required The approximate number of messages, as a positive integer, that you have available on the account identified by the Username and PIN.
  -Reserved Ignore This section should be ignored; it is reserved for use by Connection Software.

Response parameters

+AvailableMessagesResponse (required)
Operation response element
  -Messages (required)
The approximate number of messages, as a positive integer, that you have available on the account identified by the Username and PIN.
  -Reserved (ignored)
This section should be ignored; it is reserved for use by Connection Software.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">
<ns2:AvailableMessages>
<Username xsi:type="xsd:string">ANOther.12345</Username>
<PIN xsi:type="xsd:string">123456789</PIN>
</ns2:AvailableMessages>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If the Username and PIN are correct the response will be the approximate messages:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
	xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
	xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body>
<ns2:AvailableMessagesResponse>
<Messages>24</Messages>
<Reserved><Field1/><Field2/><Field3/><Field4/></Reserved>
</ns2:AvailableMessagesResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

Permitted ReplyTo

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 alpha tag 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
+PermittedReplyToResponse Required Operation response element
  -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.
  -Reserved Ignore This section should be ignored; it is reserved for use by Connection Software.

Response parameters

+PermittedReplyToResponse (required)
Operation response element
  -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.
  -Reserved (ignored)
This section should be ignored; it is reserved for use by Connection Software.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/"
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/"
	xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
	xmlns:xsd="http://www.w3.org/2001/XMLSchema"
	xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body>
<ns2:PermittedReplyTo>
<Username>ANother.12345</Username>
<PIN>123456789</PIN>
</ns2:PermittedReplyTo>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

If the Username and PIN are correct the response will be your permitted ReplyTo values. Note the reserved section which should be ignored. This is reserved for use by Connection Software.

<?xml version="1.0" encoding="UTF-8"?>
<SOAP-ENV:Envelope 
	xmlns:SOAP-ENV="http://schemas.xmlsoap.org/soap/envelope/" 
	xmlns:SOAP-ENC="http://schemas.xmlsoap.org/soap/encoding/" 
	xmlns:xsi="http://www.w3.org/1999/XMLSchema-instance" 
	xmlns:xsd="http://www.w3.org/1999/XMLSchema" 
	xmlns:ns2="http://www.csoft.co.uk/dtd/sendsms5.xsd">
<SOAP-ENV:Body>
<ns2:PermittedReplyToResponse>
<PermittedReplyTo>447700912345,csoft.co.uk</PermittedReplyTo>
<Reserved><Field1/><Field2/><Field3/><Field4/></Reserved>
</ns2:PermittedReplyToResponse>
</SOAP-ENV:Body>
</SOAP-ENV:Envelope>

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