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:

https://api-mapper.clicksend.com/rest/v2/

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.
1. Log into your account.
2. Click on your profile on the top right.
3. Then click on the Messaging Settings option.
4. Click on SMS & MMS then Inbound Rules.
5. Click the 'Add New Rule' button.
6. Select the 'Poll' action.
7. Then click 'Save'.
  
  JSON example
  
  XML example

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'.

JSON Example

XML Example

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