NAV Navbar
cURL PHP

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.

Either:

username - Your API username password - Your API key

OR

username - Your subaccount username password - Your subaccount password

The Authorization header is constructed as follows:

  1. Username and password are combined into a string "username:password"
  2. The resulting string is then encoded using Base64 encoding
  3. 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:

  1. Send the reply as an email to a nominated email address.

  2. Send the reply as an email to the original user who sent the message.

  3. Send the reply as an SMS to a nominated mobile number.

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

    1. Log into your account.
    2. Click on 'SMS' then 'Settings' tab.
    3. Click on the 'Reply/Incoming SMS Settings' menu.
    4. Select 'Forward to URL'.
    5. 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.
  5. 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 'SMS' then 'Settings' tab.
    3. Click on the 'Inbound SMS Settings' menu.
    4. Click 'Add rule'.
    5. Select 'Poll' and 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.

  1. Log into your account.
  2. Click on 'SMS' then 'Settings' tab.
  3. Click on the 'SMS Delivery Report Settings' menu.
  4. Select 'Forward to URL'.
  5. 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.

  1. Log into your account.
  2. Click on 'SMS' then 'Settings' tab.
  3. Click on the 'SMS Delivery Report Settings' menu.
  4. Select 'Poll our server' and 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.

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