in Developer Zone Tags: apierror codesxml

XML API Version 1.0

The XML API allows you to perform various actions such as sending and receiving messages, credit information and contacts.

A valid XML API request consists of an authentication section followed by as many other sections as required in any order. For example, in one API request, you could send one message to three recipients, another message to another recipient, check your inbound messages and add a contact.

The XML Document should be posted uriencoded, with a UTF-8 character set as parameter ‘xml’ to https://my.fastsms.co.uk/xmlapi

Test form

You can enter plain text in here and the request will be run on the server, with the resultant XML posted to the screen.

If an error occurs, you will be returned details of the error. For an example, see the failed login example response below. For a full list of status codes and meanings, click here

Important Note:This is an interface to the real API, so if you paste in valid XML to send a message, it will be sent to the phone.

Authentication

Request

Element Type Description
apirequest Array Container for your request
user Array Container for user related details
token Alphanumeric Used to authorize your application at FastSMS server. Required for every API call you make. You can get your token on account settings page:https://my.fastsms.co.uk/account/settings. Please note that token is updated when you change password for your FastSMS account.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
		[alphanumeric]

Response

Element Description
apiresponse Container for fastsms response
userresponse Container for user related details
status Possible values for status are: loggedin, rejected, failed.
loggedin– access credentials are valid, your request was handled successfully.
rejected– Unknown user or password, or user has been suspended
failed– An error occurred retrieving the user details
userid Your user ID within NetMesenger
Example Response
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
		loggedin
		12203

Application

Request

Element Type Description
application Array Container for application related details
name Alphanumeric A name of your application. Optional element.
version Alphanumeric A version of your application. Optional element.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
		[alphanumeric]
		[alphanumeric]

Response

No response is given.

Working with Messages

Checking Your Credit Level

Request

Element Type Description
creditcheck Empty element Include an empty creditcheck element to request your current credit level from fastsms. Do not include any value or attribute into this element.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
creditcheckresponse Decimal digit Current credit level of your fastsms account.
Example Response
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
		loggedin
		4
 
 
	173.69

Sending a message

Request

Element Type Description
sendsms Array Container of message sending request. May have a “batch” numeric attribute, which is not stored in the system, but simply used as a method in which to differentiate responses.
source Alphanumeric Will appear on mobile phones as “from” name. In example, it can be a name of your company.
destinations Array Container for message destinations. Destinations are your sending targets. They can be one of three types: mobile number, contact and distribution list. You should provide at least one destination for your message.
destination Number Use this element to specify a mobile number you want to send to. Number should be in international format, but without “+” symbol in the beginning. For the UK, mobile number starting with 077 will work as well. Example of Russia-based mobile number in international format: 79221094234.

Element may have a ref optional alphanumeric attribute, which may be used to tie a response with your request.

contact Numeric, ID Use this element to send to a contact with known ID from your contact list. Contact list is available here: https://my.fastsms.co.uk/contacts.

Element may have a ref optional alphanumeric attribute, which may be used to tie a response with your request.

list Numeric, ID Use this element to send bulk messages to your marketing lists. Note: distribution list you try to send to should exist in fastsms (so you have its ID). Also, make sure your list is not empty: your message should have actual targets to go to.

Element may have a ref optional alphanumeric attribute, which may be used to tie a response with your request.

message Alphanumeric The body of your message. Required element. Alphanumeric string. Max length for the message body is 456 characters. Message body that is longer than 160 symbols, will be split into several messages on the fastsms side.
sourceton

 

Number Source Type Of Number (optional element) – Specify the Type of Number for the source address. Only fill in this field if you know what a source TON is.
schedulefor XML date/time The date that the message should be sent (in Standard XML format, Lexical representation)
udh UDH User Data Header for the message (optional element). Only fill this in if you know that the UDH for your message is.
dcs DCS Data Coding Scheme for the message (optional element). Only fill this in if you know that the DCS for your message is.
validityperiod Numeric, seconds The period in seconds that the message will be tried for (maximum 86400 = 24 hours). Once this expires, the message will no longer be attempted to be delivered.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
		[alphanumeric]
 
 
			[number]
			[ID]
			[ID]
			<!-- ... (at least one and as many of the above three as required) -->
 
 
		[alphanumeric]
 
		<!-- Optional parameters -->
 
		[number]
 
		[time/date]
 
		[UDH]
		[DCS]
		[numeric, seconds]

Response

Element Type Description
smsresponse Array Container of message sending response. May have a “batch” numeric attribute, which is not stored in the system, but simply used as a method in which to differentiate responses.
destination Array Container for info about message you have sent a request for. Has a “number” attribute, when your send was successful. Actual number depends on what you had in your request (see request description above).

  • When you send to “destination” (raw mobile number), you just get it back in response.
  • When you send to “contact”, you get mobile number of that contact, as it is in your contact list.
  • When you send to distribution list, you get a mobile number of the last list entry.

This element also may have a “ref” attribute (if you’ve used it in your request), which is not stored in fastsms, but passed back in the response for your convenience, so you could be able to tie it with your request.

messageid Numeric, ID ID of the message you sent at fastsms. If your message 160 characters or shorter, you will get back one messageid item with part parameter set to “1”. Otherwise you may get several messageid items. Each of them will have numeric incremental part parameter, and will have different message ID values.

Message IDs are different, because long message is broken at fastsms into several 160-character pieces (parts), and each part considered as a separate sms message. Anyhow, the response contains the whole array of IDs – for your convenience.

status Alphanumeric Status of your message at fastsms by the moment of response.
error Array Container for the info about error, when your send was unsuccessful.
code Numeric Code of the error occurred while send attempt. For the whole error code list refer this list
message Alphanumeric Brief text of error description
Example Response

In this example, a message was sent to one number, two contacts and two distribution lists.
Note that when sending to a distribution list, the Number and Message ID for the last message in the list is returned.

<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			18003466
			sent
 
 
 
 
				<code>-200</code> Invalid Contact 18003467 18003468 sent <code>-408</code>Distribution List is Empty1800346918003470 sent

Checking the Status of a Message

Request

Element Type Description
messagestatuscheck Array Container for array of message ID elements (messageid).
messageid Numeric, ID Numeric value, at least one element is required. Should be ID of the message you want to check a status for.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
		[numeric]
		[numeric]

Response

Element Type Description
messagestatuscheckresponse Array Container for the message status check response.
message Array Container for message details, 1 per each message you requested status info for.
messageid Numeric ID of the message, as it was in your request.
status Alphanumeric Status value, returned by fastsms for that message ID.

Standard statuses you should usually expect for:
Unknown Message ID– no message with such ID is found in the fastsms’ database.
Pending– the message is on its way to the receiving network.
SENT– the message has been passed to the receiving network and the operator is sending it on to the recipient’s handset; we are awaiting confirmation of delivery.
DELIVERED– we have received confirmation from the handset that the message has been received.
UNDELIVERABLE– the message has been unable to reach the handset. This may be due to the number no longer being in service or the number being incorrect.
REJECTED– the number that the message was sent to does not exist or is incorrect.
You should consider any other statuses you get as failed.

Example Response
<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
			2
			Unknown Message ID
 
 
			18003448
			DELIVERED

Working with Contacts

Retrieve all contacts

Request

Element Type Description
retrieveallcontacts Empty element with attribute Include an empty retrieveallcontacts element to request a full list of your contacts stored in fastsms. Do not include any value into this element. This element should have a mode attribute, value of such an attribute can be “id” or “full”. If set to “id”, you’ll get a list of IDs for all the contacts stored in fastsms (faster option). If you set mode attribute to “full”, response will contain full contact list, where you’ll get ID, name, mobile number and email for each contact in the list.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the contact details, including ID, name, mobile number and email.
contactid Numeric, ID ID of the contact record.
name Alphanumeric Contact name, as it’s stored in fastsms. Provided only if your request had retrieveallcontacts element with mode attribute set to “full”.
number Numeric, mobile number Contact mobile number in the international format, as it’s stored in fastsms.

Provided only if your request had retrieveallcontacts element with mode attribute set to “full”.

email Valid email Contact email, as it’s stored in fastsms.

Provided only if your request had retrieveallcontacts element with mode attribute set to “full”.

Example Response

In this example, all contacts were requested in id mode.

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
			49445
 
 
			49455

Retrieve a specific contact

Request

Element Type Description
contacts Array Container for the list of contacts you want to retrieve.
contact Array Container for the request details for the specific contact you want to retrieve. To get a contact from fastsms you should add “action” attribute to this element, with value set to “retrieve”. You also can add optional alphanumeric “ref” attribute, if you want to tie you request to fastsms’ response.

Also, please note that you should include at least one child element: contactid or number, whichever suits you better.

contactid ID, numeric Use this element to pass ID of the contact you want to get details for.
number Alphanumeric Use this element to pass a mobile number of the contact you want to get full details for. Number should be in international format, without “+” character in the beginning. For the UK, numbers starting with 077 will work as well. Example: 79221094234 (Russia-based number).
Example Request

If you want to retrieve a contact by ID:

<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
		<!-- the ref is used to tie the response to the request only, not stored -->
 
			264
 
		<!-- … -->

If you want to retrieve a contact by mobile number:

<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
		<!-- the ref is used to tie the response to the request only, not stored -->
 
			447777777777
 
		<!-- … -->

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the contact details, including ID, name, mobile number and email.
contactid Numeric, ID ID of the contact record.
name Alphanumeric Contact name, as it’s stored in fastsms
number Numeric, mobile number Contact mobile number, as it’s stored in fastsms
email Valid email Contact email, as it’s stored in fastsms
Example Response
<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			49450
			Fred
			447777777777

Create a contact

Request

Element Type Description
contacts Array Container for the list of contacts you want to create.
contact Array Container for the request details for the specific contact you want to create. To create a contact at fastsms you should add “action” attribute to this element, with value set to “create”. You also can add optional alphanumeric “ref” attribute, if you want to tie you request to fastsms’ response.
name Alphanumeric Use this element to pass a name of the contact you want to create.
number Numeric, mobile number Use this element to pass a mobile number of the contact you want to create. Number should be in international format, without “+” character in the beginning. For the UK, numbers starting with 077 will work as well. Example: 79221094234 (Russia-based number).
email Valid email Valid email address for the contact you want to create.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
 
		<!-- the ref is used to tie the response to the request only, not stored -->
 
			[alphanumeric, only for create or edit]
			[alphanumeric for create or edit, optional for retrieve]
			[alphanumeric, only for create or edit]
 
		<!-- … -->

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the contact details, including ID, name, mobile number and email.
contactid Numeric, ID ID of the new contact record. This ID is assigned by fastsms automatically upon creation.
error Alphanumeric If an error occurs during processing your request, response will contain this element. Value of this element will be a brief text description of the error.
Example Response

If contact was added successfully:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			49450

If there was an error:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
			One or more fields are invalid

Edit contact

Request

Element Type Description
contacts Array Container for the list of contacts you want to create.
contact Array Container for the request details for the specific contact you want to create. To create a contact at fastsms you should add “action” attribute to this element, with value set to “edit”. You also can add optional alphanumeric “ref” attribute, if you want to tie you request to fastsms’ response.
contactid Numeric, ID Use this element to pass an ID of the contact record you want to update.
name Alphanumeric Use this element to pass a new name of the contact you want to update.
number Numeric, mobile number Use this element to pass a new mobile number of the contact you want to update. Number should be in international format, without “+” character in the beginning. For the UK, numbers starting with 077 will work as well. Example: 79221094234 (Russia-based number).
email Valid email New valid email address for the contact you want to update.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
 
		<!-- the ref is used to tie the response to the request only, not stored -->
 
			542
			John Smith
			447777777777
 
 
		<!-- … -->

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
contact Array Container for the specific contact details, including ID, name, mobile number and email.
status Alphanumeric If your edit request was processed successfully, you will get this element with value set to “Saved”.
error Alphanumeric If an error occurs during processing your request, response will contain this element. Value of this element will be a brief text description of the error.
Example Response

If the record was updated successfully:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			Saved

If there was an error:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			One or more fields are invalid

Delete all contacts

Use this method with care! When it’s processed successfully, it wipes out all your contacts from the fastsms database.

Request

Element Type Description
contacts Array Container for the action requested. Usually there will be a contact list, but for this method, you should just include one child element – deleteallcontacts
deleteallcontacts Empty element Include this element into your request when you want to delete all the contacts you have in the fastsms database. Do not include any attribute or value into this element.
Please note: contacts will be deleted permanently.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
contactsresponse Array Container for the contact manipulation response.
deleteallcontacts Array Container for response details specific for deleteallcontacts request. Has child elements, which may be status, number of contacts deleted and/or error details.
status Alphanumeric Resulting status of your request. Can be one of the following:
“DELETED” (if you had contacts and they were deleted successfully)
“NO CONTACTS TO DELETE” (if you had no contacts to delete)
“ERROR”, if your request triggered an error while processing.
When status is an “ERROR”, fastsms adds to response an error element with error code and description as child elements.
contactdeletetotal Numeric Total number of contacts you have just deleted. If the status element (see above) will be “NO CONTACTS TO DELETE” or “ERROR”, you will get zero here.
error Array When your request was handled with an error, you will get error details in this element.
code Numeric Code of the error occurred. Refer to this list for all error codes.
message Alphanumeric Brief description of the error occurred.
Example Response

If you deleted all the contacts successfully:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			DELETED
			8

If you have no contacts to delete:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			NO CONTACTS TO DELETE
			0

If there was an error:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			ERROR
			0
 
				<code>-300</code>DB Error

Inbound Numbers and SMS Templates

Get a List of Inbound Numbers

Request

Element Type Description
getinboundnumbers Empty element Send this element with your request to get a list of all inbound numbers existing in your account at fastsms. Do not include any attributes or child elements.

Note: you should purchase inbound numbers via fastsms interface first to use this method.

Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
getinboundnumbersresponse Array Container for the inbound number list.
msisdn Array Container for response details about specific inbound number.
id Numeric, ID ID of the specific inbound number
number Numeric, mobile number Number in the international format, without “+” sign in the beginning. I.e.: 447777777777
Example Response
<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			142
			447777777777
 
 
			356
			447777777778

Check for Inbound Messages

Request

Element Type Description
inboundcheck Empty element with attributes Send this element with your request to get inbound messages stored in the fastsms database. You can use two attributes in this element:
lastid (numeric) – ID of the message you want to use as a starting point for response. In this case fastsms will respond with the list of messages with IDs which were received later the message you’ve specified.
from (xml date/time) –  a date you want to use as a starting point for response. Fastsms will provide a list of messages which were received after this date/time.

Date format: YYYY-MM-DDTHH:MM:SS+/-TZ:TZ example: 2009-05-09T13:23:50+01:00 (more about format).

If this date will not be specified, fastsms will use a span of the last 7 days by default.

Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
inboundcheckresponse Array Container for the response part with details about inbound messages.
sms Array Container for the details about specific inbound message.
messageid Numeric, ID ID of the specific inbound message
source Numeric, mobile number Source of the specific inbound message. A mobile number this specific message was sent from, in international format.
destination Numeric, mobile number Target number for the specific message. This is one of your MSISDNs (inbound numbers), in international format.
Example Response
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
    loggedin
    4
 
 
 
      23464567567
 
      447777777777
 
      447777777778
      2009-05-09T13:23:50+00:00
 
      This is an example message
 
 
 
      34574574
 
      447777777777
 
      447777777778
      2009-05-09T13:27:17+00:00
 
      This is another example message

Get the Templates from fastsms

Request

Element Type Description
getsmstemplates Empty element with attribute Use this element to request a list of your sms templates stored in fastsms. Include the lastid numeric parameter to specify which template you want response to start with. Do not include any child elements here.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
getsmstemplatesresponse Array A container for the part of the response with sms template list.
template Array A container for the part of the response with details about specific sms template
templateid Numeric, ID ID of the specific sms template
name Alphanumeric Name of the specific sms template.
body Alphanumeric Body of the specific sms template. Max length of the body is 456 characters. Note: is the body is longer than 160 symbols, it will produce up to 3 actual messages (160 symbols or less per each).
Example Response
<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
    loggedin
    4
 
 
 
      1192
      template 1
 
      This is an SMS Template
 
 
 
      1193
      Renewal Reminder
 
      Dear #Name#, your account is due for renewal in the next 7 days

Working with Distribution lists

Retrieve all Distribution Lists

Request

Element Type Description
retrievealllists Empty element Use this element to request the set of your distribution lists stored in fastsms. Response will include IDs and titles of your distribution lists. Do not include any child elements here.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
distributionlistsresponse Array A container for the part of the response with details of your distribution lists.
distributionlist Array Container for the details on the specific distribution list.
listid Numeric, ID ID of the specific distribution list. You can use it for further list entries request.
title Alphanumeric Title of the specific distribution list.
Example Response
<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			1693
 
 
 
			1692

Get Details of Specific Distribution List

Request

Element Type Description
getdetails Empty element with attribute Use this element to request list details and entries for the specific distribution list. Include listid numeric parameter to specify an ID of the list you want to retrieve. Do not include any child elements here.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
distributionlist Array Container for the response part with list details and list entries you requested for.
listid Numeric, ID ID of the list you requested.
title Alphanumeric Title of the list you requested.
entries Array Container for the array of the list entries.
entry Array Container for the details of the specific entry.
entryid Numeric, ID ID of the specific entry record
number Numeric, mobile number Mobile number of the specific list entry, should be in the international format without “+” symbol in the beginning, i.e.: 447777777777
name Alphanumeric Name of the specific list entry. I.e., this could be a person name.
email Valid email A valid email address for the specific entry.
mailmerge1… mailmerge5 Alphanumeric Mail merge fields. Consider them as custom extension fields for the distribution list entry.

When this element is a child of the “distributionlist” element, its value is a name of the mail merge field (in example, let it be “handset model”).

When this element is a child of the “entry” element, its value should be an actual value of the mail merge field assigned to the specific entry (let it be “Nokia 6820” for our example).

You can use up to 5 mail merge fields in your distribution lists.

Example Response
<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			1692
 
			make
			model
 
 
					67602
					447777777777
					Me
 
					Nokia
					6820
 
 
					67801
					447777777778
					Me
					me@nowhere.com
					Motorola
					V3
 
 
					67806
					49455
					Me as a contact
					me@nowhere.com
					Sony Eriksson
					C905

Add, Replace and Merge a Distribution List

Request

Element Type Description
addlist Array Use this element to add a new distribution list. You will need to provide a title for a new list as a child element (see title element).

First, fastsms will check a title of the list you try to add. If you have no any existing distribution lists with such title, fastsms will add it.

For a case when list with such a title already exists, you should set onexisting attribute to one of the following values (if such an attribute will not exist in your request, fastsms will consider it as existing and set to “skip”):

skip” – if you want to leave the existing list untouched. In this case, when fastsms will find existing list with duplicate title during adding a new list, it will just stop sorting your request.

replace” – if you want to replace existing list. In this case fastsms will replace existing list details and entries with those you sent with your addlist request.

merge” – if you want to merge entries of the new list with the existing one. Note: if duplicate entry is encountered in the existing list, and existing list doesn’t allow duplicates, it will be replaced with the details of the entry from the new list.

append” – if you want to append entries of the new list to the existing one. Note: if duplicate entry is encountered in the existing list, and existing list doesn’t allow duplicates, such entry will be skipped.

 

Note: you can use ref alphanumeric attribute if you want to tie your request with the response from fastsms.

 

title Alphanumeric Title of the list you want to apply action to.
allowduplicates Numeric Value can be “1” or “0”. Indicates if your list allows duplicates. When duplicates are not allowed, fastsms will replace (while list merge), or skip (while list append) duplicate records in existing lists.

Also, when you add a list using replace action, a value of this element will be used as a setting for a new list.

mailmerge1… mailmerge5 Alphanumeric Mail merge fields. Consider them as custom extension fields for the distribution list entry.

If this element is a child for addlist, it’s value should be set to mail merge field name (i.e., “car make”). Note, merge fields are used only when your onexisting attribute for the addlist element is set to “replace”.

If this element is a child for entry element, it’s value should be actual content of the field for the specific entry (i.e., “bmw”).

You can use up to 5 mail merge fields in your distribution lists.

entries Array Container for the array of the list entries.
entry Array Container for the details of the specific entry.
entryid Numeric, ID ID of the specific entry record
number Numeric, mobile number Mobile number of the specific list entry, should be in the international format without “+” symbol in the beginning, i.e.: 447777777777
name Alphanumeric Name of the specific list entry. I.e., this could be a person name.
email Valid email A valid email address for the specific entry.
Example Request

If you want to add a new list:

<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
 
 
 
 
					447777777777
					Me1
 
 
 
					447777777778
					Me2
					me@nowhere.com

If you want to replace an existing list, and do not want it to have duplicates (existing entries will be replaced when duplicates are encountered):

<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
 
 
			0
			Account Number
			Reference
 
 
					447777777777
					Me1
 
					34653
					ABC123
 
 
					447777777778
					Me2
 
					34654
					ABC124

If you want to merge your data with an existing list:

<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
 
 
 
 
					447777777777
					Me1

If you want to append your data to an existing list:

<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0
 
 
 
 
 
 
 
					447777777777
					Me1

Response

Element Type Description
addlist Array Container for the response part related to your addlist request. May have a “ref” alphanumeric attribute, the same as you had in your request so you could tie request and response.
status Alphanumeric Status of the action you requested for. Can be one of the following:
CREATED– if new list have been added successfully.
SKIPPED– if there is a list with the same title as the list in your request, and onexisting attribute was set to “skip” or was not specified.
REPLACED– if there was a list with the same title, which have been replaced with the new list you’ve sent in your request (in case you’ve set onexisting attribute to “replace”).
MERGED– If there is a list with the same title as list in your request and you had “onexisting” attribute set to “merge” in your request.
APPENDED– If there is a list with the same title as list in your request and you had “onexisting” attribute set to “append” in your request.
FAILED– if there was an error during processing your request.
listid Numeric, ID ID of the list which fastsms applied an action to.
title Alphanumeric Title of the list which fastsms applied an action to.
entries Array Container for the details about entry processing totals.
replacetotal Numeric Total number of the existing list entries replaced with duplicate entries from your request.Note: If the action was to replace the list, then all entries are appended to a new list, so the replacetotal will be 0 in this case.
appendtotal Numeric Total number of your list entries appended to the existing list.
skiptotal Numeric Total number of the list entries skipped during processing your request.
invalidtotal Numeric Total number of entries considered as invalid during processing your request.
failtotal Number Total number of entries which were processed with error.
Example Response

When you successfully added a new list (list ID is for the new list):

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			CREATED
			23534654
 
 
				0
				10
				0
				0
				0

When you tried to add a new list, but you already have a list with such a title and onexisting attribute is not set or set to “skip” (list ID is for existing list):

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			SKIPPED
			23534654

When you successfully replaced an existing list (all entries are appended to a new list, so the replacetotal will be 0):

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			REPLACED
			23534654
 
 
				0
				10
				0
				0
				0

When you successfully merged your data with an existing list, and that list doesn’t allow duplicates:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
			MERGED
			23534654
 
 
				5
				5
				0
				0
				0

When you successfully appended your data to an existing list, and that list doesn’t allow duplicates:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			APPENDED
			23534654
 
 
				0
				5
				5
				0
				0

When there was an error while handling your request:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			FAILED
			23534654

Delete a Distribution List

Request

Element Type Description
deletelist Array Use this element in your request if you want to delete a distribution list at fastsms. Element may have a “ref” alphanumeric attribute if you want to tie your request with the response from API.
title Alphanumeric Title of the distribution list you want to delete.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
deletelist Array Container for the part of the response related to the delete action. May have a ref alphanumeric attribute (the same as those you used in your request).
title Alphanumeric Title of the deleted list.
status Alphanumeric Action status. Can be one of the following:
DELETED– if the list was deleted successfully
ERROR– if there was an error while processing action.
error Array Container for the details on the error (if any occurred while processing your request).
code Numeric Code of the error occurred. For the full error code list click here. Typical error codes you may get for the delete action are:

-516 (if the list you try to delete does not exist)

-301 (if list deletion failed)

message Alphanumeric Brief text description for the error.

Descriptions for typical errors are:

“Unknown List” – for 516 error code

“DB Error” – for the 301 error code

Example Response

If you successfully deleted the list:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			DELETED

If the list you tried to delete doesn’t exist:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
			ERROR
 
				<code>-516</code>Unknown List

If there was an error while trying to delete a list:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
 
			ERROR
 
				<code>-301</code>DB Error

Delete All Distribution Lists

Request

Element Type Description
deletealllists Empty element Use this element in your request if you want to delete all distribution lists at fastsms. Do not include any child element or attribute here.
Example Request
<!--?xml version="1.0" encoding="UTF-8"?-->
 
 
 
		[alphanumeric]
 
 
 
		Example Application
		1.0

Response

Element Type Description
deletealllists Array Container for the part of the response related to the delete-all-lists action.
status Alphanumeric Action status. Can be one of the following:
DELETED– if the list was deleted successfully
NO LISTS TO DELETE– if you have no distribution lists at fastsms
ERROR– if there was an error while processing action.
distributionlistdeletetotal Numeric Total number of the deleted distribution lists.
error Array Container for the error details, when there is any.
code Numeric Code of the error occurred. For the full error code list click here.
message Alphanumeric Brief text describing an error occurred.
Example Response

If you successfully deleted all lists:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			DELETED
			8

If you have no lists to delete:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			NO LISTS TO DELETE
			0

If there was an error while handling your request:

<!--?xml version="1.0" encoding="UTF-8" ?-->
 
 
		loggedin
		4
 
 
 
 
 
 
			ERROR
			0
 
				<code>-300</code>DB Error

Appendix

Date Format

Standard XML format – http://www.w3.org/TR/xmlschema-2/#dateTime:

3.2.7.1 Lexical representation

The ·lexical space· of dateTime consists of finite-length sequences of characters of the form: ‘-‘? yyyy ‘-‘ mm ‘-‘ dd ‘T’ hh ‘:’ mm ‘:’ ss (‘.’ s+)? (zzzzzz)?, where

  • ‘-‘? yyyy is a four-or-more digit optionally negative-signed numeral that represents the year; if more than four digits, leading zeros are prohibited, and ‘0000’ is prohibited (see the Note above (§3.2.7); also note that a plus sign is not permitted);
  • the remaining ‘-‘s are separators between parts of the date portion;
  • the first mm is a two-digit numeral that represents the month;
  • dd is a two-digit numeral that represents the day;
  • ‘T’ is a separator indicating that time-of-day follows;
  • hh is a two-digit numeral that represents the hour; ’24’ is permitted if the minutes and seconds represented are zero, and the dateTime value so represented is the first instant of the following day (the hour property of a dateTime object in the ·value space· cannot have a value greater than 23);
  • ‘:’ is a separator between parts of the time-of-day portion;
  • the second mm is a two-digit numeral that represents the minute;
  • ss is a two-integer-digit numeral that represents the whole seconds;
  • ‘.’ s+ (if present) represents the fractional seconds;
  • zzzzzz (if present) represents the timezone (as described below).

 

For example, 2002-10-10T12:00:00-05:00 (noon on 10 October 2002, Central Daylight Savings Time as well as Eastern Standard Time in the U.S.) is 2002-10-10T17:00:00Z, five hours later than 2002-10-10T12:00:00Z.

Error Codes

Code Description
-100 Not Enough Credits
-101 Invalid CreditID
-200 Invalid Contact
-300 General Database Error
-301 Unknown Error
-302 Return XML Error
-303 Received XML Error
-400 Some numbers in list failed
-401 Invalid Destination Address
-402 Invalid Source Address – Alphanumeric too long
-403 Invalid Source Address – Invalid Number
-404 Blank Body
-405 Invalid Validity Period
-406 No Route Available
-407 Invalid Schedule Date
-408 Distribution List is Empty
-409 Group is Empty
-410 Invalid Distribution List
-411 You have exceeded the limit of messages you can send in a single day to a single number
-412 Number is blacklisted
-414 Invalid Group
-501 Unknown Username/Password
-502 Unknown Action
-503 Unknown Message ID
-504 Invalid From Timestamp
-505 Invalid To Timestamp
-506 Source Address Not Allowed (Email2SMS)
-507 Invalid/Missing Details
-508 Error Creating User
-509 Unknown/Invalid User
-510 You cannot set a user’s credits to be less than 0
-511 The system is down for maintenance
-512 User Suspended
-513 License in use
-514 License expired
-515 No License available
-516 Unknown List
-517 Unable to create List
-601 Unknown Report Type
-701 No UserID Specified
-702 Invalid Amount Specified
-703 Invalid Currency Requested

0