> For the complete documentation index, see [llms.txt](https://docs.appmixer.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.appmixer.com/connector-configuration/cliniko.md). # Cliniko ## Prerequisites Before using Cliniko components in Appmixer, you need: 1. A Cliniko account — 2. An API key generated from your own Cliniko user profile 3. A Cliniko user whose permissions cover the data your flows touch (see [Permissions](#permissions)) {% hint style="info" %} **There is no OAuth app to register.** Cliniko's API is API-key only — there is no OAuth app console, no client ID or secret, and no multitenant app to submit for verification. Every user connects with their own key. If you are looking for the "register your app" step other guides in this section have, Cliniko simply does not have one. {% endhint %} *** ## 1. Generate an API Key 1. Log into Cliniko 2. Open **My Info** from your user menu 3. Go to **Manage API keys** 4. Create a new API key and give it a name that says where it is used, e.g. `Appmixer` 5. Copy the generated key Keys belong to a **user**, not to the account — each Cliniko user has their own. {% hint style="warning" %} The key is **only shown once**, at creation time. Copy it before you close the dialog — if you lose it, delete the key and create a new one. {% endhint %} Cliniko documents this at . ## 2. Connect in Appmixer When adding a Cliniko component you will be prompted to authenticate. Provide: | Field | Value | | ----------- | --------------------------- | | **API Key** | The key generated in Step 1 | That is the only field. **You do not need to pick a region.** Cliniko is sharded: accounts are hosted per region, and the shard is appended to the API key itself: ``` MS0xMjM0NTY3ODkwLUV4YW1wbGVLZXlOb3RSZWFsRG9Ob3RVc2VUaGlz-eu1 ↑ shard ``` Appmixer reads that suffix and calls `https://api.{shard}.cliniko.com/v1`. Keys generated before Cliniko introduced sharding carry no suffix and are treated as `au1`, which is what Cliniko does too. The current shards are: | Region | Shards | | ------ | ----------------------------- | | AU | `au1` `au2` `au3` `au4` `au5` | | CA | `ca1` | | UK | `uk1` `uk2` `uk3` | | EU | `eu1` | See [Base URL and shards](https://docs.api.cliniko.com/guides/urls) for the current list. The key is sent as the HTTP Basic **username** with an empty password, as Cliniko requires. *** ## Permissions An API key inherits the permissions of the Cliniko user it belongs to — it is not a separate, independently-scoped credential. A key belonging to a receptionist-role user authenticates fine and then returns **403** on the resources that role cannot see, most commonly treatment notes. If some components work and others return "Access denied (403)", the key is almost certainly attached to the wrong user. Generate the key from a user whose role covers the data your flows need, rather than trying to widen the key. ## Online bookings and available times **Find Available Times** and **Get Next Available Time** read Cliniko's online-bookings availability. Cliniko returns **404** — not an empty result — when the business, the practitioner or the appointment type is not published to online bookings. To use them, enable online bookings in Cliniko for all three: * the **business** (clinic location) * the **practitioner** * the **appointment type** Cliniko also caps the window at **7 days** and will not look into the past. In Appmixer both date fields are optional: leave them empty and the components query the next seven days. ## Rate limit Cliniko allows **200 requests per minute per user**. Polling triggers and paginated Find components both consume that budget, so a flow polling several Cliniko triggers on a large account can approach it. Appmixer throttles Cliniko calls below the limit; if you still see "Rate limit exceeded (429)", reduce how many Cliniko triggers run concurrently on the same account. *** ## Available Components ### Actions | Component | Description | | --------------------------- | ------------------------------------------------------------------------- | | **Find Patients** | Search patients by name, email or date of birth | | **Get Patient** | Retrieve a patient by ID | | **Create Patient** | Create a patient (Last Name is required) | | **Update Patient** | Update an existing patient | | **Archive Patient** | Archive a patient (hidden from Cliniko, not destroyed) | | **Unarchive Patient** | Restore a previously archived patient | | **Find Appointments** | Search individual appointments by date, patient, practitioner or business | | **Get Appointment** | Retrieve an individual appointment by ID | | **Create Appointment** | Book an individual appointment | | **Update Appointment** | Reschedule or edit an appointment | | **Cancel Appointment** | Cancel an appointment with a cancellation reason | | **Find Available Times** | Bookable start times for a practitioner, in a date window | | **Get Next Available Time** | The single next bookable start time | | **List Practitioners** | List the practitioners in the account | | **List Businesses** | List the businesses (clinic locations) | | **List Appointment Types** | List the configured appointment types | | **Find Treatment Notes** | Search treatment notes by patient, practitioner or draft status | | **Create Treatment Note** | Create a treatment note for a patient | | **Create Medical Alert** | Add a medical alert to a patient | | **Find Invoices** | Search invoices by patient, practitioner, business, status or issue date | | **Find Contacts** | Search contacts (referring doctors, third-party payers) | | **Create Contact** | Create a contact | | **Make API Call** | Call any Cliniko API endpoint | ### Triggers | Component | Description | | ------------------------- | ----------------------------------------------------------------- | | **New Patient** | A new patient was created | | **Updated Patient** | A patient record changed | | **New Appointment** | A new individual appointment was booked | | **Updated Appointment** | An individual appointment changed | | **Cancelled Appointment** | An individual appointment was cancelled | | **New Booking** | A new booking appeared in the calendar (includes online bookings) | | **New Invoice** | A new invoice was created | {% hint style="info" %} **Cliniko has no webhooks**, so every trigger polls. Two consequences: events arrive on the polling interval rather than instantly, and the first run after you start a flow only records a baseline — it does not replay records that already existed. **Updated Patient** and **Updated Appointment** poll the record's "updated at" timestamp, which also moves when a record is created, so they fire on new records too. {% endhint %} *** ## Troubleshooting ### "Authentication failed (401)" The key is wrong, or it was deleted in Cliniko. Check for whitespace pasted around the key, and confirm the key still exists under **My Info > Manage API keys**. ### "Access denied (403)" on some components only The key belongs to a Cliniko user whose role cannot access that resource — see [Permissions](#permissions). Treatment notes are the usual case. ### "Not found (404)" from Find Available Times or Get Next Available Time The business, practitioner or appointment type is not enabled for online bookings — see [Online bookings and available times](#online-bookings-and-available-times). Cliniko answers 404 rather than returning an empty list. ### Requests reach the wrong Cliniko account, or 401 on a key that works elsewhere The shard suffix on the key is what selects the account. A key that was copied without its trailing `-eu1` (or similar) is treated as an `au1` key and will not authenticate against the right shard. Re-copy the whole key. ### "Validation failed (422)" when creating a patient or contact Cliniko requires **Last Name** on a patient, and a **First Name or Last Name** on a contact — a company name alone is not enough. The error message names the field Cliniko rejected. ### A trigger does not fire Confirm the flow has been running long enough for a second poll: the first run only takes a baseline. Also check the trigger's optional Practitioner / Business filters — a filter set to a record from a different account matches nothing. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.appmixer.com/connector-configuration/cliniko.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.