ClickSend REST API v3 1.0.0
Added: 13/01/2021
Updated at: 12/07/2021
This is the official API documentation for ClickSend.com Below you will find a current list of the available methods for clicksend. **NOTE**: You will need to create a free account to use the API. You can [**Register Here**](https://dashboard.clicksend.com/#/signup/step1/). # API URL The API should always be accessed over SSL. Base URL: `https://rest.clicksend.com/v3/` # Authentication Basic HTTP authentication should be used in the header. **Either:** `username`: Your API username `password`: Your API key ``` You can get your API credentials by clicking 'API Credentials' on the top right of the dashboard. ``` **OR** `username`: Your account username `password`: Your account password ``` These are the same credentials that you use to login to the dashboard. ``` ### Authorization Header The Authorization header is constructed as follows: 1. Username and password are combined into a string `username:password` 1. The resulting string is then encoded using Base64 encoding 1. The authorization method and a space i.e. "Basic " is then put before the encoded string. For example, if the user uses `Aladdin` as the username and `open sesame` as the password then the header is formed as follows: `Authorization: Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==` ### PHP Authentication Header Example (using cURL) `curl_setopt($ch, CURLOPT_HTTPHEADER, ['Authorization: Basic ' . base64_encode("$username:$password")]);` # 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 | Response | Description | |---|---|---| | `200` | `SUCCESS` | Request completed successfully. | | `400` | `BAD_REQUEST` | The request was invalid or cannot be otherwise served. An accompanying error message will explain further. | | `401` | `UNAUTHORIZED` | Authentication credentials were missing or incorrect. | | `403` | `FORBIDDEN` | The request is understood, but it has been refused or access is not allowed. An accompanying error message will explain why. | | `404` | `NOT_FOUND` | The URI requested is invalid or the resource requested does not exists. | | `405` | `NOT_FOUND` | Method doesn't exist or is not allowed. | | `429` | `TOO_MANY_REQUESTS` | Rate Limit Exceeded. Returned when a request cannot be served due to the application’s rate limit having been exhausted for the resource. See Rate Limiting. | | `500` | `INTERNAL_SERVER_ERROR` | Something is broken | # Application Status Codes The following status codes can be returned in addition to the HTTP status code. For example, when using the Send SMS endpoint: | Response | Description | |---|---| | `SUCCESS` | Message added to queue OK. Use delivery reports to get an update on the delivery status.| | `MISSING_CREDENTIALS` | Not enough information has been supplied for authentication. Please ensure that your Username and Unique Key are supplied in your request.| | `ACCOUNT_NOT_ACTIVATED` | Your account has not been activated.| | `INVALID_RECIPIENT` | The destination mobile number is invalid.| | `THROTTLED` | Identical message body recently sent to the same recipient. Please try again in a few seconds.| | `INVALID_SENDER_ID` | Invalid Sender ID. Please ensure Sender ID is no longer than 11 characters (if alphanumeric), and contains no spaces.| | `INSUFFICIENT_CREDIT` | You have reached the end of your message credits. You will need to purchase more message credits.| | `INVALID_CREDENTIALS` | Your Username or Unique Key is incorrect.| | `ALREADY_EXISTS` | The resource you're trying to add already exists.| | `EMPTY_MESSAGE` | Message is empty.| | `TOO_MANY_RECIPIENTS` | Too many recipients.| | `MISSING_REQUIRED_FIELDS` | Some required fields are missing.| | `INVALID_SCHEDULE` | The schedule specified is invalid. Use a unix timestamp e.g. 1429170372.| | `NOT_ENOUGH_PERMISSION_TO_LIST_ID` | Don't have enough privilege to access or send to a list_id.| | `INTERNAL_ERROR` | Internal error.| | `INVALID_LANG` | An invalid language option has been provided.| | `INVALID_VOICE` | An invalid voice (gender) option has been provided.| | `SUBJECT_REQUIRED` | Usually happens when MMS Subject is empty.| | `INVALID_MEDIA_FILE` | Usually MMS media file is invalid file.| | `SOMETHING_IS_WRONG` | Generic Error happened.| # Required Headers You'll need to send some headers when making API calls. | Header | Value | |---|---| | `Content-type` | `application/json` | # Pagination Some methods are paginated. By default, 1 page of 15 items will be returned. You can set the pagination parameters by adding `?page={page}&limit={limit}` to the URL. ## Request | Parameter | Type | Default | Value | |---|---|---|---| | `page` | integer | `1` | The page number to return in the response. | | `limit` | integer | `15` | The number of results per page. Min 15, Max 100. | ## Response | Attribute | Type | Value | |---|---|---|---| | `total` | integer | Total number of results available. | | `per_page` | integer | Number of results returned per page. | | `current_page` | integer | Current page number. | | `last_page` | integer | Last page number. | | `next_page_url` | string | A URL of the next page. `null` if not available.| | `prev_page_url` | string | A URL of the previous page. `null` if not available.| | `from` | integer | Number of the first result in current page. | | `to` | integer | Number of the last result in current page. | # Searching and Sorting Most GET endpoints allow searching and sorting. Searches are **not** case-sensitive. ## Search To perform a search, add `q` as a query parameter. For example: `/subaccounts?q=field:value,field2:value` ## Order To perform a sort, add `order_by` as a query parameter. For example: `/subaccounts?order_by=field:desc/asc` ## AND / OR By default, it will search using the `AND` operator. This can be set using `operator` as a query parameter. For example: `/subaccounts?q=field:value&operator=OR` **Options:** - `AN` - returns results matching **all** query fields specified - `OR` - returns results matching **any** query fields specified ## Example `/subaccounts?q=first_name:john,last_name:smith&order_by=subaccount_id:asc&operator=AND` # CORS When creating your API app, specify the JavaScript (CORS) origins you'll be using. We use these origins to return the headers needed for CORS. # Date and Time All date/timestamps will be returned in Unix time (also known as POSIX time or erroneously as Epoch time) with no leap seconds. For example: `1435255816` ``` (ISO 8601: 2015-06-25T18:10:16Z) ``` More information: [Wikipedia: Unix time](https://en.wikipedia.org/wiki/Unix_time). There is ony one Unix time and it is created by using the UTC/GMT time zone. This means you might have convert time zones to calculate timestamps. Most programming language have libraries to help you converting time zones. **The current Unix time can be found here:** [Epoch Converter](http://www.epochconverter.com) # 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/MMS 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` - `+8615555555555` ## Test Voice 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` - `+8615555555555` ## Test Fax 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. - `+61261111111` - `+61262222222` - `+61263333333` ## Test Email Addresses The following email addresses can be used when testing. No messages will be sent, and your account won't be charged. A success response will be returned. - `test1@test.com` - `test2@test.com` - `test3@test.com` ## Test Post Letter Addresses The following Postal Codes (address_postal_code) can be used when testing. No messages will be sent when using these post codes, and your account won't be charged. A success response will be returned. - `11111` - `22222` - `33333`