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.

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

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

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