Introduction
The REST API (application programming interface) is simple, lightweight and built on simple and established standards that reduce the need for special toolkits. This allows ClickSend to support a wider range of programming languages more easily than ever before.
This document describes the REST interactions the API offers to the business messaging services provided by ClickSend. It is intended to provide all the information required to get started using the API.
The REST API has been based on the REST architectural style and has been implemented on the HTTP protocol. It uses the standard HTTP methods of GET, POST, PUT and DELETE to interact with a set of defined resources.
Responses are available in json or XML.
NOTE: You will need to create a free account to use the API. You can register here..
API URL
The API should always be accessed over SSL.
Base URLs:
Authentication
Basic HTTP authentication should be used in the header.
username
: Your API username
password
: Your API key
The Authorization header is constructed as follows:
- Username and password are combined into a string "username:password"
- The resulting string is then encoded using Base64 encoding
- The authorization method and a space i.e. "Basic " is then put before the encoded string.
For example, if the user agent uses 'Aladdin' as the username and 'open sesame' as the password then the header is formed as follows:
Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==
Verbs
The API uses restful verbs.
Verb | Description |
---|---|
GET |
Select one or more items. Success returns 200 status code. |
POST |
Create a new item. Success returns 200 status code. |
PUT |
Update an item. Success returns 200 status code. |
DELETE |
Delete an item. Success returns 200 status code. |
Status Codes
The API will respond with one of the following HTTP status codes.
Code | Description |
---|---|
200 | OK |
400 | Bad Request |
401 | Not Authorized |
404 | Resource Not Found |
408 | Request Timed Out |
500 | Problem with REST API |
Response Codes
The API will always respond with a 200 OK HTTP status code.
Response Code | Error Text | Description |
---|---|---|
0000 |
Success | Message added to queue OK. |
2006 |
Missing credentials | Not enough information has been supplied for authentication. Please ensure that your Username and Unique Key are supplied in your request. |
2007 |
Account not activated | Your account has not been activated. |
2015 |
Invalid recipient | The destination mobile number is invalid. |
2016 |
Throttled | Identical message already sent to this recipient. Please try again in a few seconds. |
2017 |
Invalid sender id | Invalid Sender ID. Please ensure Sender ID is no longer than 11 characters (if alphanumeric), and contains no spaces. |
2018 |
Low credit | You have reached the end of your message credits. You will need to purchase more message credits. |
2022 |
Invalid credentials | Your Username or Unique Key is incorrect. |
2051 |
Empty message | Message is empty. |
2052 |
Too many recipients | Too many recipients. |
2100-2199 |
Internal error | Internal error. |
Security
To ensure privacy, we recommend you use HTTPS for all API requests.
Reply Options
There are 5 options for handling message replies:
Send the reply as an email to a nominated email address.
Send the reply as an email to the original user who sent the message.
Send the reply as an SMS to a nominated mobile number.
Push - POST the reply to your website or application.
If you prefer, we can push message replies to your server as they arrive with us.
- Log into your account.
- Click on your profile on the top right.
- Then click on the Messaging Settings option.
- Click on SMS & MMS then Inbound Rules.
- Click the 'Add New Rule' button.
- Select the 'URL' action.
- Enter the URL and click 'Save'.
The following parameters will be POSTED to the URL specified.
Parameter Type Description from
string Recipient Mobile Number that sent the reply message. message
string Reply SMS message body. originalmessage
string Original SMS message body. originalmessageid
string Original SMS message ID. Returned when originally sending the message. originalsenderid
string Original mobile number (sender ID) that the SMS was sent from. customstring
string A custom string used when sending the original message. username
string The API username used to send the original message. Pull
Receive SMS by polling your Inbox. You can poll our server and retrieve new Messages at a time that suits you.
- Log into your account.
- Click on your profile on the top right.
- Then click on the Messaging Settings option.
- Click on SMS & MMS then Inbound Rules.
- Click the 'Add New Rule' button.
- Select the 'Poll' action.
Then click 'Save'.
To change how message replies are handled, log in to your account area and navigate to the Settings page.
Delivery Reports
PUSH
If you prefer, we can push message replies to your server as they arrive with us.
- Log into your account.
- Click on your profile on the top right.
- Then click on the Messaging Settings option.
- Click on SMS & MMS then Inbound Rules.
- Click the 'Add New Rule' button.
- Select the 'URL' action.
- Enter the URL and click 'Save'.
The following parameters will be POSTED to the URL specified.
Parameter | Type | Description |
---|---|---|
messageid |
string | SMS message ID. Returned when originally sending the message. |
status |
string | Delivery status. Either 'Delivered' or 'Undelivered'. |
status_code |
integer | Delivery status code. The temporary status codes can update at any time. |
customstring |
string | A custom string used when sending the original message. |
username |
string | The API username used to send the original message. |
PULL
Receive delivery reports by polling. You can poll our server and retrieve delivery reports at a time that suits you.
- Log into your account.
- Click on your profile on the top right.
- Then click on the Messaging Settings option.
- Click on SMS & MMS then Inbound Rules.
- Click the 'Add New Rule' button.
- Select the 'Poll' action.
Then click 'Save'.
Note: a delivery report won't be generated when using a test number.
Testing
Test Credentials
These API credentials can be used to test specific scenarios.
Note: you will need to create a free account to test other scenarios. Refer to introduction.
API Username | API Key | Description |
---|---|---|
nocredit |
D83DED51-9E35-4D42-9BB9-0E34B7CA85AE |
This account has no credit. |
notactive |
D83DED51-9E35-4D42-9BB9-0E34B7CA85AE |
This account is not active. |
banned |
D83DED51-9E35-4D42-9BB9-0E34B7CA85AE |
This account is banned. |
Test SMS Numbers
The following numbers can be used when testing. No messages will be sent, and your account won't be charged. A success response will be returned.
+61411111111
+61422222222
+61433333333
+61444444444
+14055555555
+14055555666
+447777777777
+447778888888
+8615555555555
A message added to queue 'Success' response will be returned. No SMS will actually be sent. This won't use any of your credit. A delivery report won't be generated when using a test number.
Account Balance
Account Balance - JSON
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://api-mapper.clicksend.com/rest/v2/balance.json'
Response
{
"result":"0000",
"errortext":"Success",
"balance":"125.00",
"credit":"1785",
"type":"Prepay",
"currency_symbol":"$"
}
https://api-mapper.clicksend.com/rest/v2/balance.json
Retrieve a JSON Response
Account Balance - XML
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://api-mapper.clicksend.com/rest/v2/balance.xml'
Response
<?xml version='1.0' encoding='UTF-8' ?>
<xml>
<result>0000</result>
<errortext>Success</errortext>
<balance>125.00</balance>
<credit>1785</credit>
<type>Prepay</type>
<currency_symbol>$</currency_symbol>
</xml>
https://api-mapper.clicksend.com/rest/v2/balance.xml
Retrieve a XML Response
SMS
Send an SMS - JSON
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary " {
\"message\":\"test message\",
\"senderid\":\"MyCompany\",
\"customstring\":\"my_ref\",
\"schedule\":1435100575
}" \
'https://api-mapper.clicksend.com/rest/v2/send.json'
Request
to=61411111111&message=testing
Response
{
"recipientcount":"2",
"messages":[
{
"to":"+61411111111",
"messageid":"D9F15F83-34EC-6A31-A57E-7E8FB0966D78",
"result":"0000",
"errortext":"Success"
},
{
"to":"+61422222222",
"messageid":"F15F83H8-15AC-3R31-777E-7E8FB09SSDP2",
"result":"0000",
"errortext":"Success"
}
]
}
https://api-mapper.clicksend.com/rest/v2/send.json
Retrieve a JSON Response
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
to |
body | string | true | Recipient Mobile Number in international format (with leading + and country code). Separate multiple recipients with a comma (,) where applicable. Maximum 1000 recipients. |
message |
body | string | true | The message to be sent. Maximum 960 characters. |
senderid |
body | string | false | custom sender ID (from name/number) |
schedule |
body | string | false | Allows you to schedule message delivery. Must be in unix format. |
customstring |
body | string | false | A custom string that will be passed back with replies and delivery reports. Maximum 50 characters. |
Send an SMS - XML
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
--header "Content-Type: application/json" \
--data-binary " {
\"message\":\"test message\",
\"senderid\":\"MyCompany\",
\"customstring\":\"my_ref\",
\"schedule\":1435100575
}" \
'https://api-mapper.clicksend.com/rest/v2/send.xml'
Request
to=61411111111&message=testing
Response
<?xml version='1.0' encoding='UTF-8' ?>
<xml>
<messages recipientcount='2'>
<message>
<to>+61411111111</to>
<messageid>D9F15F83-34EC-6A31-A57E-7E8FB0966D78</messageid>
<result>0000</result>
<errortext>Success</errortext>
</message>
<message>
<to>+61422222222</to>
<messageid>F15F83H8-15AC-3R31-777E-7E8FB09SSDP2</messageid>
<result>0000</result>
<errortext>Success</errortext>
</message>
</messages>
</xml>
https://api-mapper.clicksend.com/rest/v2/send.xml
Retrieve a XML Response
Parameters
Parameter | In | Type | Required | Description |
---|---|---|---|---|
to |
body | string | true | Recipient Mobile Number in international format (with leading + and country code). Separate multiple recipients with a comma (,) where applicable. Maximum 1000 recipients. |
message |
body | string | true | The message to be sent. Maximum 960 characters. |
senderid |
body | string | false | custom sender ID (from name/number) |
schedule |
body | string | false | Allows you to schedule message delivery. Must be in unix format. |
customstring |
body | string | false | A custom string that will be passed back with replies and delivery reports. Maximum 50 characters. |
Receive an SMS - JSON
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
'https://api-mapper.clicksend.com/rest/v2/reply.json'
Response
{
"replycount":"2",
"replies":[
{
"from":"+61411111111",
"message":"This is a reply",
"originalmessage":"Hello. Please reply",
"originalmessageid":"D9F15F83-34EC-6A31-A57E-7E8FB0966D78",
"originalsenderid":"+61400000000",
"customstring":"",
"username":"testuser101"
},
{
"from":"+61422222222",
"message":"This is another reply",
"originalmessage":"Hello. Please reply",
"originalmessageid":"F15F83H8-15AC-3R31-777E-7E8FB09SSDP2",
"originalsenderid":"+61400000000",
"customstring":"",
"username":"testuser101"
}
],
"result":"0000",
"errortext":"Success"
}
https://api-mapper.clicksend.com/rest/v2/reply.json
Retrieve a JSON Response
Receive an SMS - XML
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
'https://api-mapper.clicksend.com/rest/v2/reply.xml'
Response
<?xml version='1.0' encoding='UTF-8' ?>
<xml>
<replies replycount='2'>
<reply>
<from>+61411111111</from>
<message>This is a reply</message>
<originalmessage>Hello. Please reply</originalmessage>
<originalmessageid>D9F15F83-34EC-6A31-A57E-7E8FB0966D78</originalmessageid>
<originalsenderid>+61400000000</originalsenderid>
<customstring></customstring>
<username>testuser101</username>
</reply>
<reply>
<from>+61422222222</from>
<message>This is another reply</message>
<originalmessage>Hello. Please reply</originalmessage>
<originalmessageid>F15F83H8-15AC-3R31-777E-7E8FB09SSDP2</originalmessageid>
<originalsenderid>+61400000000</originalsenderid>
<customstring></customstring>
<username>testuser101</username>
</reply>
</replies>
<result>0000</result>
<errortext>Success</errortext>
</xml>
https://api-mapper.clicksend.com/rest/v2/reply.xml
Retrieve a XML Response
Get Delivery Reports - JSON
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
'https://api-mapper.clicksend.com/rest/v2/delivery.json'
Response
{
"dlrcount":"2",
"dlrs":[
{
"messageid":"D9F15F83-34EC-6A31-A57E-7E8FB0966D78",
"status":"Delivered",
"status_code":"201",
"customstring":"",
"username":"testuser101"
},
{
"messageid":"F15F83H8-15AC-3R31-777E-7E8FB09SSDP2",
"status":"Undelivered",
"status_code":"301",
"customstring":"",
"username":"testuser101"
}
],
"result":"0000",
"errortext":"Success"
}
https://api-mapper.clicksend.com/rest/v2/delivery.json
Retrieve a JSON Response
Get Delivery Reports - XML
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
--request POST \
'https://api-mapper.clicksend.com/rest/v2/delivery.xml'
Response
<?xml version='1.0' encoding='UTF-8' ?>
<xml>
<dlrs dlrcount='2'>
<dlr>
<messageid>D9F15F83-34EC-6A31-A57E-7E8FB0966D78</messageid>
<status>Delivered</status>
<status_code>201</status_code>
<customstring></customstring>
<username>testuser101</username>
</dlr>
<dlr>
<messageid>F15F83H8-15AC-3R31-777E-7E8FB09SSDP2</messageid>
<status>Undelivered</status>
<status_code>301</status_code>
<customstring></customstring>
<username>testuser101</username>
</dlr>
</dlrs>
<result>0000</result>
<errortext>Success</errortext>
</xml>
https://api-mapper.clicksend.com/rest/v2/delivery.xml
Retrieve a XML Response
SMS History - JSON
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://api-mapper.clicksend.com/rest/v2/history.json'
Response
{
"historycount":"x",
"items":[
{
"messageid":"D9F15F83-34EC-6A31-A57E-7E8FB0966D78",
"direction":"out",
"date":"1414291144",
"to":"+61411111111",
"message":"This is a test message",
"status":"Sent",
"senderid":"MyCompany",
"schedule":"1414291144",
"customstring":"our-ref-1234",
"from_email":"test@email.com"
},
{
"messageid":"F15F83H8-15AC-3R31-777E-7E8FB09SSDP2",
"direction":"in",
"date":"1414291155",
"to":"+61422222222",
"message":"This is a test message reply",
"status":"Received",
"senderid":"+61411111111",
"schedule":"",
"customstring":"our-ref-1234",
"from_email":"test@email.com"
}
],
"result":"resultCode",
"errortext":"error-message"
}
https://api-mapper.clicksend.com/rest/v2/history.json
Retrieve a JSON Response
SMS History - XML
Code samples
curl --include \
--header "Authorization: Basic YXBpLXVzZXJuYW1lOmFwaS1wYXNzd29yZA==" \
'https://api-mapper.clicksend.com/rest/v2/history.xml'
Response
<?xml version='1.0' encoding='UTF-8' ?>
<xml>
<history historycount='2'>
<item>
<messageid>D9F15F83-34EC-6A31-A57E-7E8FB0966D78</messageid>
<direction>out</direction>
<date>1414291144</date>
<to>+61411111111</to>
<message>This is a test message</message>
<status>Sent</status>
<senderid>MyCompany</senderid>
<schedule>1414291144</schedule>
<customstring>our-ref-1234</customstring>
<from_email>test@email.com</from_email>
</item>
<item>
<messageid>F15F83H8-15AC-3R31-777E-7E8FB09SSDP2</messageid>
<direction>in</direction>
<date>1414291155</date>
<to>+61422222222</to>
<message>This is a test message reply</message>
<status>Received</status>
<senderid>+61411111111</senderid>
<schedule></schedule>
<customstring>our-ref-1234</customstring>
<from_email>test@email.com</from_email>
</item>
<result>0000</result>
<errortext>Success</errortext>
</history>
</xml>
https://api-mapper.clicksend.com/rest/v2/history.xml
Retrieve a XML Response