in Developer Zone Tags: apierror codeshttpmessage format

Connecting to the API

The URL for accessing the API from within your script is: https://my.fastsms.co.uk/api

The API can be called with an HTTP GET or POST, passing in the relevant parameters. All parameters are mandatory unless otherwise stated. All parameters must be URI Encoded.

General Parameters

The general parameters are applicable to all calls to the API

Parameter NameDescription
Token (required)Your token (found in your settings within NetMessenger)
Action (required)The action that you would like to perform. This must be one of (not case sensitive):
CheckCredits to check how many credits you have
CheckMessageStatus to check the status of a message
Send to send a message
Report to create a report
CreateUser to create a new user
UpdateCredits to add/remove credits from an existing user
ImportContactsCSV to import contacts
DeleteAllContacts to delete all contacts
DeleteAllGroups to delete all contact groups
ShowErrorMessage (optional)If this is set (to any value) and an error occurs in the API call, the text for the error message will be shown one line beneath the error code.

Check Credits

Checks your current credit balance. No further parameters are required. Your credit balance will be returned in the content of the page.

Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=CheckCredits

Check Message Status

Parameter NameDescription
MessageIDThe Message ID of the message that you wish to query. This is the ID returned by the Send action and can also be found in a message report
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=CheckMessageStatus&MessageID=[Your Message ID]

Send Message

Sends a message. The message ID or error code will be returned in the content of the Page. If multiple numbers are submitted, then multiple IDs / error codes will be returned, separated by commas

Parameter NameDescription
DestinationAddressThe Destination Address(es) to send the message to. If you wish to send to multiple numbers, they should be separated by a comma. When submitting multiple numbers, you should use the POST method rather than the GET method.To send to a list, set the DestinationAddress parameter to “List” and add a new parameter “ListName” with the name of the list to send to.For a group set the DestinationAddress parameter to “Group” and add a new parameter “GroupName” with the name of the group to send to.If the send is successful, the API will return 1. If not, a negative error code will be returned.Note that these sends may occur in the background if the group/list contains more than 200 entries.
SourceAddressThe Source Address for the message. If this is alphanumeric, it must be 11 or less characters. All GSM characters are valid, however operators and handsets may support restricted character sets. We recommend you stick to A-Z, a-z, 0-9 and space.
BodyThe Message Body (max 459 characters)
ScheduleDate (optional)The date that the message should be sent (YYYYMMDDHHMMSS)
SourceTON (optional)The Type Of Number for the source address (1 for international, 5 for alphanumeric)
ValidityPeriodThe 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.
GetAllMessageIDsIf the message is longer than 160 characters, the system by default will return only the first ID for each message. Set this parameter to 1 to return all the Ids for each part of each message.
GetBGSendIDIf you send to a distlist and set this parameter to 1 the BGSendID for the dist list will be returned. For future proofing, this could be a comma separated list of values, should the send be split into multiple sends.
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=Send&DestinationAddress=[Your Number]&SourceAddress=API&Body=Hello%20World

Cancel Message

Parameter NameDescription
MessageIDThe Message ID (This is the ID returned by the Send action and can also be found in a message report) of the message that you wish to cancel, if that message has not been sent. If the message has been sent, does not belong to that user or does not exist, a -503 error (invalid message ID) will be returned.
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=CancelMessage&MessageID=[Your Message ID]

Reports

Retrieve the data from a report. The report, in CSV format, will be returned in the content of the page.

Parameter NameDescription
ReportTypeThe Type of report. Options are: Outbox (From and To dates are ignored for this report), Messages, Usage, InboundMessages, FailedMessages
FromThe start date for the report (YYYYMMDDHHMMSS)
ToThe end date for the report (YYYYMMDDHHMMSS)
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=Report&ReportType=Messages&From=20130704000000&To=20130711000000

Create User

Only possible if you are an admin user, this will create a child user. If successful, ‘1’ will be returned in the content of the page. If unsuccessful, the first line of the page will be the error code and the following lines will contain text information about the nature of the error(s).

Parameter NameDescription
ChildUsernameThe username of the user you wish to create
ChildPasswordThe password for the user
AccessLevelWhat access level the user should have (Normal or Admin)
FirstNameThe first name of the user
LastNameThe last name of the user
EmailThe email address of the user
Telephone (Optional)The telephone number of the user
CreditsHow many credits the user should start with (these will be deducted from your account)
Credit Reminder (Optional)When to send the user a low credit warning email (number of credits left to trigger the email)
Alert (Optional)After how many days of inactivity should an inactivity alert be sent
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=CreateUser&ChildUsername=[Child Username]&ChildPassword=[Child Password]&AccessLevel=Normal&FirstName=[User’s First Name]&LastName=[User’s Last Name]&Email=[User’s Email]&Credits=5

Update Credits

Transfer credits to/from a child user. If successful, ‘1’ will be returned in the content of the page.

Parameter NameDescription
ChildUsernameThe username of the user that you wish to transfer credits to/from. The user must belong to you.
QuantityThe amount of credits to transfer. If the number is positive, credits will be transferred to that user. If the number is negative, they will be transferred from that user to you.
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=UpdateCredits&ChildUsername=[Child Username]&Quantity=5

Import Contacts CSV

This allows you to import contacts into your address book.

For each line in the ContactsCSV parameter, a corresponding line will be returned in the content of the page in the format:

[line] : [result]

Where result is one of:

Success
Duplicate Name
Duplicate Number
Partial
Failed

If there are any Partial or Failed lines, then there will be a blank line, followed by text with details of all the errors below. Partial will usually mean that the contact was added, but could not be put in the group.

Example:

ContactsCSV Parameter contains:
Contact 1,447777777771,noone@anywhere.com,group1
Contact 2,447777777772,
Contact 3,447777777773,,group1,group2,group3
,447777777774,noone@anywhere.com,group3
Contact 5,mynumber,noone@anywhere.com,group3

Gives the reponse:

1 : Success
2 : Success
3 : Success
4 : Failed
5 : Failed

Errors:

4 : No name
5 : Invalid number (mynumber)

Parameter NameDescription
ContactsCSVA comma separated list of contacts to add, one per line formatted as follows: name,number,email,group1,group2,group3
IgnoreDupes (Optional)If set to 1, the system will allow duplicate contacts (name or number) to be created. By default the system will not allow duplicate names or numbers in contacts.
OverwriteDupes (Optional)is set to 1, the value of IgnoreDupes is ignored.
OverwriteDupes (Optional)is set to 1, then any duplicate number will be overwritten. If a duplicate name exists, but with a different number, the original contact will not be overwritten, instead a new contact will be created.
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=ImportContactsCSV&ContactsCSV=contact%201%2C447777777777%2Cnoreply%40anywhere.com%2Cgroup1%2Cgroup2%2Cgroup3%0Acontact%202%2C447777777778%2Cnoreply%40anywhereelse.com%2Cgroup1%2C

Get All Contacts/Groups

Retrieve Your Contacts or Groups. They are in CSV format and will be returned in the content of the page.

Parameter NameDescription
GetAllContactsReturns a CSV with all your contacts.
GetAllGroupsReturns a CSV with all your groups.
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=GetAllContacts

Delete All Contacts

Deletes all contacts in this account. No further parameters are required. 1 will be returned if the deletion was successful, the relevant error code will be returned if an error occurred.

Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=DeleteAllContacts

Delete All Groups

Deletes all groups. No further parameters are required. 1 will be returned if the deletion was successful, the relevant error code will be returned if an error occurred.

Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=DeleteAllGroups

Empty Group

Remove all contacts from the specified group

Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=EmptyGroup&Group=MyGroupName

Delete Group

Delete the specified group

Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=DeleteGroup&Group=MyGroupName

GetBGMessages

Returns a JSON array of MessageID/Number/Status objects (e.g. [{“MessageID”:”3509592″,”Destination”:”447777777777″,”Status”:”Sent”},{“MessageID”:”3509593″,”Destination”:”447777777778″,”Status”:”Sent”}]
or a json error array as follows: {“error”:”-521″,”message”:”Unknown Background SendID”}

Possible errors:
-521 : Unknown Background Send ID
-522 : Background Send Not Finished
-523 : No messages were found

This function will be unable to access messages that have been archived.

Parameter NameDescription
BGSendIDID of the send you want to retrieve messages for.
Example GET URL : https://my.fastsms.co.uk/api?Token=th1S-15my-t0ken&Action=GetBGMessages&BGSendID=[BGSendID]

Inbound Message HTTP Forwarding

If you have bought an Virtual Mobile Number (VMN or MSISDN), you can set up the system to forward messages sent to that VMN to a web page on your website.

To do this, login into the web interface, go to your inbox and click on the manage button for the VMN you want to forward.

Once there you will be able to choose the URL to forward to, whether you want to forward with the GET or POST method and what to pass with the auth parameter. (The auth parameter is a passthrough variable designed to add some security by having a password passed through)

The following parameters are used in the call to your site:

source – the phone number that the message came from

dest – the VMN that the message was received on

msg – the body of the message

id – the ID of the message

receivedts – the timestamp that the message was received by us in the format YYYY-MM-DD HH:MM:SS

auth – the passthrough variable defined in manage VMN on the web interface

Supplemental Data from a Distribution List

If you have selected a distribution list to receive supplemental data from, you will receive the following additional parameters, with data from the mail merge fields of that list

MMName – the data from the Name field

MMEmail – the data from the Email field

MM1 – the data from the first mail merge field

MM2 – the data from the second mail merge field

MM3 – the data from the third mail merge field

MM4 – the data from the fourth mail merge field

MM5 – the data from the fifth mail merge field

Error Codes

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