🚨 Our API documentation has moved to https://docs.api.cliniko.com/developer-portal/ 🚨

This github documentation repo will no longer be kept up to date as of 15th Nov 2022.

⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️⬆️

The Cliniko API

This is the offical API for Cliniko. Cliniko is a practice management system for healthcare practitioners.

The Cliniko API is based on REST principles. This means you can use any HTTP client and any programming language to interact with the API.

JSON will be returned in all responses from the API.

Security

The Cliniko API is served over HTTPS to ensure data security and privacy. HTTP is not supported.

Ensure that the HTTP client is up-to-date and has the latest TLS, cipher suites and SNI available. It's recommended that the client uses the cipher offered by the Cliniko API. It's not recommended to hard-code TLS versions or ciphers.

From May 1, 2018, requests to the Cliniko API will require TLS 1.2. See the guide on How do I test my API client? for more information.

An API Key from Cliniko will allow access to sensitive information. Handle the key securely like you would a password.

Base URL & shards

All URLs in this documenation will use the following base, where {shard} is the Cliniko shard the account resides in. You can determine which shard to use through the Cliniko API key. API keys have the shard appended to the end, e.g. MS0xLWl4SzYYYYdtR3V2HNOTAREALKEYwvNHdeW0pd-au2 is in the shard au2. If your API key was generated some time ago and has no shard on it, your shard will be au1.

https://api.{shard}.cliniko.com/v1

Examples in this guide will typically use au1 as the shard, unless the example requires otherwise. Please ensure you use the appropriate shard for your requests.

Current regions and their shards

Region	Shard
AU	`au1`
AU	`au2`
AU	`au3`
CA	`ca1`
UK	`uk1`
EU	`eu1`

It is strongly advisable that you validate the shard component:

being one of these shard values, or
matches the regex /\w{2}\d{1,2}/i

For more about the introduction of shards, and a code example of API keys with the shard attached may be used, read the guide.

Authentication

The Cliniko API uses HTTP Basic authentication. This is secure, as all requests are via SSL.

Each Cliniko user will have their own API Key(s) - these are used for authentication. The API Key will have the same permissions as the user it belongs to.

You should provide the Cliniko API Key (either with or without the shard suffix) as the basic auth username. There is no need to provide a password. This should be sent in the Authorization header. The psuedocode for how the Authorization header should be built is:

"Basic " + base64_encode(api_key + ":")

For example, if your API key is MxJrZXkiOiI1Njd1amJmZTQ1NyJ9-au2, then you would generate your Authorization header like so, using the API Key as the username:

"Basic " + base64_encode("MxJrZXkiOiI1Njd1amJmZTQ1NyJ9-au2" + ":")

resulting in your Authorization header value:

Basic TXhKclpYa2lPaUkxTmpkMWFtSm1aVFExTnlKOS1hdTI6

To obtain an API key for testing, sign up for a free trial and go to the "My Info" link in the bottom left corner of the navigation within Cliniko. Click the "Manage API keys" button, you can create an API key from that page. If you need your trial extended just let us know.

An API Key from Cliniko will allow access to sensitive information. Handle the key securely like you would a password.

Identifying your application

To identify your application, you need to send the User-Agent header. In the event of an issue, this allows us to easily track down your requests and contact you. This should be in the form:

APP_VENDOR_NAME (APP_VENDOR_EMAIL)

APP_VENDOR_NAME is the name of your application APP_VENDOR_EMAIL is a contact email address for you or your company

As an example, a valid User-Agent value would be something like: Really helpful app (devs@helpfulapp.com)

If your requests do not include a User-Agent that contains a name and valid contact email, future requests may be automatically blocked.

Errors

Conventional HTTP response codes are used to indicate API errors.

General code rules apply:

2xx range indicate success.
4xx range indicate an error resulting from the provided information (eg. missing a required parameter)
5xx range indicate an error with our Cliniko servers

Making a request

All URLs start with https://api.{shard}.cliniko.com/v1. SSL only. The path is prefixed with the API version. If we change the API in backward-incompatible ways, we'll bump the version marker and maintain stable support for the old URLs.

To make a request for all the patients on a specific account in the au1 shard, you'd append the patients index path to the base url like this: https://api.au1.cliniko.com/v1/patients. In curl, that looks like:

Example Request

curl https://api.au1.cliniko.com/v1/patients \
  -u API_KEY: \
  -H 'Accept: application/json' \
  -H 'User-Agent: APP_VENDOR_NAME (APP_VENDOR_EMAIL)'

Note: curl uses the -u flag to pass basic auth credentials (adding a colon after the API key will prevent it from asking for a password).

API_KEY is the API Key provided by the Cliniko user

Make sure to send the Accept header with application/json.

That's all!

Rate limits

API requests are rate limited to 200 per minute per user. We recommend you design your app to stagger requests to avoid hitting the rate limit.

Requests exceeding the rate limit will receive a response with a 429 status and an X-RateLimit-Reset header containing the time at which the limit will reset. The time is formatted as a UNIX timestamp of elapsed seconds since the start of the UNIX epoch in the UTC timezone.

Requests that exceed our fair use allocation may be blocked. If you require a higher rate limit, please contact us.

Data Responses

We only support JSON for serialization of data.

Dates and Times

All dates and times are expected to be in UTC.

Pagination

Requests that return multiple items will be paginated to 50 items by default. You can specify further pages with the page parameter. You can also set a custom page size up to 100 with the per_page parameter.

All paginated requests will return the total number of entries that exist as total_entries in the response.

The pagination info is included in the links object. It is recommended to follow these links instead of constructing your own URLs.

"appointments": {
  ...
},
total_entries: 400,
"links": {
  "next": "https://api.au1.cliniko.com/v1/appointments?page=4&per_page=100",
  "self": "https://api.au1.cliniko.com/v1/appointments?page=3&per_page=100",
  "previous": "https://api.au1.cliniko.com/v1/appointments?page=2&per_page=100"
}

The possible pagination links are:

next Shows the URL of the immediate next page of results.

self Shows the URL of the current page of results.

previous Shows the URL of the immediate previous page of results.

The pagination links will only be included if they are relevant (eg. there will be no next link if you are on the last page.

Filtering Results

Some resources allow the results to be filtered. This will be documented with the resource if it is available.

Date Filter Operators

= Equal to
>= Greater than or equal to
> Greater than
<= Less than or equal to
< Less than

Dates must be in YYYY-MM-DD format. The date filter accepts wildcards in this format using *. Ex: ****-05-** will return all patients born in May.

DateTime Filter Operators

>= Greater than or equal to
> Greater than
<= Less than or equal to
< Less than

Integer Filter Operators

= Equal to
!= Not equal to
>= Greater than or equal to
> Greater than
<= Less than or equal to
< Less than

String Filter Operators

= Equals
!= Not equal to
~ Contains
~~ Wildcard search (%)

Filter String Format

The filter string format is [FIELDNAME]:[OPERATOR][VALUE]

The integer = operator also accepts a list of integers in the format: [FIELDNAME]:=[VALUE],[VALUE],[VALUE],[VALUE]. For example, practitioner_id:=1,2,3.

Sending Filter Parameters

To filter a resource, send a filter string as the q parameter:

https://api.au1.cliniko.com/v1/appointments?q=appointment_start:>2014-03-04T20:37:17Z

To apply multiple filters, send multiple filter strings as an array with the q[] parameter:

https://api.au1.cliniko.com/v1/appointments?q[]=appointment_start:>2014-03-04T20:37:17Z&q[]=appointment_start:<2014-04-04T20:37:17Z

The q[] method also works for a single filter string:

https://api.au1.cliniko.com/v1/appointments?q[]=appointment_start:>2014-03-04T20:37:17Z

Example Request (Greater than)

curl https://api.au1.cliniko.com/v1/appointments?q=appointment_start:>2014-03-04T20:37:17Z \
  -u API_KEY: \
  -H 'Accept: application/json' \
  -H 'User-Agent: APP_VENDOR_NAME (APP_VENDOR_EMAIL)'

Example Request (Contains)

curl https://api.au1.cliniko.com/v1/patients?q=last_name:~son \
  -u API_KEY: \
  -H 'Accept: application/json' \
  -H 'User-Agent: APP_VENDOR_NAME (APP_VENDOR_EMAIL)'

Example Request (Wildcard Search)

curl https://api.au1.cliniko.com/v1/patients?q=last_name:~~ja%on% \
  -u API_KEY: \
  -H 'Accept: application/json' \
  -H 'User-Agent: APP_VENDOR_NAME (APP_VENDOR_EMAIL)'

Example Request (Multiple Filters)

curl https://api.au1.cliniko.com/v1/patients?q%5B%5D=first_name:~bri&q%5B%5D=last_name:~son \
  -u API_KEY: \
  -H 'Accept: application/json' \
  -H 'User-Agent: APP_VENDOR_NAME (APP_VENDOR_EMAIL)'

In this example, q[] is encoded as q%5B%5D so this command works properly in a terminal.

Format Rules

DateTime has to be in UTC if present – e.g. 2014-08-30T18:00:00Z.

Filtering Tips

% is the wildcard symbol for the wildcard search operator. You may need to escape it (%25).
You can use multiple %'s in a wildcard search.
The contains operator is the same as doing %value% with the wildcard search.
You can get records that have been updated since a certain time by sending a filter for updated_at. Ex: q=updated_at:>2014-08-30T18:00:00Z

Ordering

By default, API results are ordered in ascending direction by their created_at timestamps.

You can specify a custom column to order by sending the sort parameter as the column name (eg. sort=appointment_start). You can also send multiple columns to sort by (eg. sort=appointment_start,created_at).

You can also specify the order direction by sending the order parameter set to desc or asc (eg. order=desc). If you need to order a column in the other direction, you can specify the order in the sort parameter (eg. sort=appointment_start,created_at:desc).

Availability times are not able to be custom ordered, they are always returned chronologically.

API Resources

Custom Patient Button

Cliniko offers an additional integration option for applications that handle patient data. See this guide for more details.

Telehealth links

Telehealth in Cliniko includes the generation of appointment Telehealth links. To understand what these are and how to use them, see this guide for more details.

Stay up to date and get involved

Join Cliniko API Developers Group to stay updated with any changes and exchange information with Cliniko API Developers and others using the API.

For feature requests or bugs please use GitHub issues. You can also fork this project and send a pull request with any improvements.

Need to talk to us privately? Send an email through to support@cliniko.com and we'll make sure it gets to the developers.

Do not send any real Cliniko API Key to the Google Group, or via email. Doing so may result in your application being blocked for security concerns.

redguava / cliniko-api

readme