|
Account Query Web Services SOAP 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 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 identing 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.
Authentication, Security and Fail-over
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.
We support both SOAP over HTTP and HTTPS but we strongly recommend HTTPS for greater security of your account information.
We have two public SOAP services, as shown below. We strongly urge you to implement fail-over to the secondary service in the event that the primary service is unavailable. Should we ever need to take down a service, we will always seek to ensure that the other is still running.
| Primary Service Address |
https://www.csoft.co.uk/sendsms5 http://www.csoft.co.uk/sendsms5 |
| Secondary Service Address |
https://www2.csoft.co.uk/sendsms5 http://www2.csoft.co.uk/sendsms5 |
| Username | Is automatically supplied when you sign-up for the service. |
| PIN | Is automatically supplied when you sign-up for the service. |
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.
| 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 |
|---|---|---|
| +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. |
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.
| 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 be the approximate number of premier messages on that account.
| 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. |
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 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.
| 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 |
|---|---|---|
| +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. |
<?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.