> ## Documentation Index
> Fetch the complete documentation index at: https://docs.intavia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Cliniko setup

> Connect Intavia to Cliniko and configure Cliniko so availability and booking work correctly.

# Cliniko Integration Setup Guide

## TL;DR - Quick Setup

**You need a Cliniko API key from a dedicated Scheduler user** (recommended for security).

**Required Settings in Cliniko:**

1. **API User** - Create a dedicated "Intavia Integration" user with Scheduler role
2. **Online bookings (global)** - Turn on online bookings and enable "Allow your patients to book appointments online"
3. **Business** - Enable "Show in Online Bookings"
4. **Practitioner(s)** - Enable "Show in Online Bookings"
5. **Appointment Type(s)** - Enable "Show in Online Bookings"
6. **Daily Availabilities** - Configure working hours for each practitioner
7. **Assign Practitioners to Appointment Types** - Link which practitioners provide which services (Step 9 below)

**Quick Steps:**

1. Create a Scheduler user for Intavia (see Step 1 below)
2. Enable API key creation for that user
3. Log in as the Intavia user and generate an API key
4. Copy the full API key (includes region suffix like `-au1` or `-eu1`)
5. In Cliniko: Turn on online bookings globally (Settings → Appointments → Online bookings)
6. In Cliniko: Enable online bookings for Business, Practitioners, and Appointment Types
7. Intavia → Integrations → Cliniko → Paste API key → Connect

***

## Why These Settings Matter

Cliniko availability and booking only work reliably when **all of these conditions** are met:

* Online bookings are enabled globally (Settings → Appointments → Online bookings)
* Business has online bookings enabled
* Practitioner has online bookings enabled
* Appointment type has online bookings enabled
* Practitioner has daily availabilities configured
* **Appointment type is assigned to the practitioner** (this is separate from "Show in Online Bookings")

If any one is missing, the agent won't be able to find or book appointments.

## Voice Agent Behavior (Important)

* **Practitioner is required for booking.** When the caller has no practitioner preference, the agent checks availability across all eligible practitioners and presents named slots. Booking always requires a specific practitioner.
* **Only “Show in Online Bookings” items are used.** If a practitioner or appointment type isn’t marked “Show in Online Bookings” in Cliniko, it won’t be offered by the agent.

***

## Step-by-Step Instructions

### 1. Create a Scheduler User for Intavia

We recommend creating a dedicated user with the **Scheduler** role for Intavia. This provides the minimum permissions needed to manage appointments while protecting sensitive patient data.

1. Go to **Settings** → **[Users & practitioners](https://help.cliniko.com/en/articles/1087380-add-a-user-to-cliniko)**
2. Click **+ Add user**
3. Fill in the user details:
   * **First name:** `Intavia`
   * **Last name:** `Integration`
   * **Email:** Use a shared/service email your team controls
4. Under **Security role**, select **Scheduler**
5. Click **Create user**

> **Why Scheduler?** The Scheduler role can book, modify, and cancel appointments, view basic patient details, and send SMS messages — but cannot access financials, treatment notes, or completed patient forms. This follows the principle of least privilege. See [User security roles](https://help.cliniko.com/en/articles/1087327-user-security-roles) for details on what each role can access.

### 2. Enable API Key Creation for the User

By default, Scheduler users cannot create API keys. An Administrator must grant this permission:

1. As an Administrator, go to **Settings** → **Users & practitioners**
2. Click on the **Intavia Integration** user you just created
3. Scroll down to find **"Intavia Integration cannot create or use API keys"**
4. Toggle **"Allow Intavia to create and use API keys"** to **Yes**
5. Click **Update user**

### 3. Generate the API Key

Now log in as the Intavia Integration user to create the API key:

1. Log into Cliniko as the **Intavia Integration** user (check email for login invitation)
2. Click your name in the bottom-left corner → **My info**
3. Scroll to **"You have 0 API keys"** and click **Manage API keys**
4. Click **Create new API key**
5. Name it `Intavia Integration`
6. **Copy the API key immediately** — it won't be shown again

> **Important:** The API key includes a region suffix (e.g., `-au1`, `-eu1`, `-uk1`). Copy the **entire key** including this suffix — it tells Intavia which Cliniko data center your account is on.

### 4. Turn On Online Bookings (Global)

1. **Settings** → **Appointments** → **Online bookings**
2. Click **Turn on online bookings**
3. Ensure **Allow your patients to book appointments online** is enabled ✅
4. Save

### 5. Enable Online Bookings for Business

1. **Settings** → **Business information** (under "Our clinic" section)
2. You'll see your business listed (e.g., "Intavia")
3. Click **"Edit information"** button
4. Scroll down to find **"Display this business in online bookings"**
5. Toggle it to **On** ✅
6. Click **"Update business"** to save

### 6. Enable Online Bookings for Practitioners

1. **Settings** → **Users** (left sidebar)
2. Click on each practitioner name
3. In the **Online Bookings** section, enable **"Show in Online Bookings"** ✅
4. **Save**

Repeat for each practitioner who should be bookable via the AI agent.

### 7. Enable Online Bookings for Appointment Types

1. **Settings** → **Appointment Types** (left sidebar)
2. Click on each appointment type
3. Enable **"Show in Online Bookings"** ✅
4. **Save**

Repeat for each appointment type that should be available for booking.

### 8. Configure Daily Availabilities

1. Go to **Appointments** (calendar view)
2. Click **Availability** in the left sidebar
3. Click **Adjust schedule**
4. For each practitioner:
   * Set working hours for each day of the week
   * Example: Monday-Friday, 9:00 AM - 5:00 PM
5. **Save**

> **Important:** Without daily availabilities, the API has no time slots to offer even if everything else is enabled.

### 9. Assign Appointment Types to Practitioners

> **Critical for Intavia:** This step is often overlooked but is essential. Even if Cliniko's built-in booking widget shows availability, Intavia requires explicit practitioner assignments to access availability via the API.

1. **Settings** → **Appointment Types**
2. Click on an appointment type
3. Scroll to **Practitioners** section
4. Check the practitioners who can provide this appointment type
5. **Save**
6. **Repeat for all appointment types** you want Intavia to offer

### 10. Connect in Intavia

1. **Intavia** → **Integrations** → **Cliniko** → **Connect**
2. **Paste your API key** (the full key including the `-region` suffix)
3. Click **Connect**

Done! Your agent can now handle appointments via Cliniko.

***

## What Can Intavia Access?

When using the recommended **Scheduler** role, Intavia can:

**✅ Intavia CAN:**

* View businesses/locations
* View practitioners and their availability
* View appointment types
* Search for patients (basic details only)
* Create new patients
* Book, reschedule, and cancel appointments
* View patient appointments
* Send SMS messages to patients

**❌ Intavia CANNOT:**

* Access financial or billing data
* View treatment notes or completed patient forms
* Delete patients
* Modify practice settings
* View confidential patient details

> This follows the principle of least privilege — Intavia only has access to what it needs to manage appointments. See [Cliniko's Scheduler role documentation](https://help.cliniko.com/en/articles/1087327-user-security-roles) for the complete permissions list.

***

## Troubleshooting

### "Invalid API key format" error

Your API key is missing the region suffix.

**Fix:** The full key should end with something like `-au1`, `-eu1`, `-uk1`, `-us1`, or `-ca1`. Log in as the Intavia Integration user, go to **My Info** → **Manage API keys**, and copy the complete key including the suffix.

### "Could not validate credentials" error

The API key is incorrect or has been revoked.

**Fix:**

1. Log into Cliniko as the **Intavia Integration** user
2. Go to **My Info** → **Manage API keys**
3. Delete the old key
4. Generate a new one named `Intavia Integration`
5. Copy the entire key (including region suffix) and paste it in Intavia

### Agent can't find any availability

The agent reports no available times even though your Cliniko calendar shows openings.

**Most common cause:** Appointment types are not assigned to practitioners. This is a **separate setting** from "Show in Online Bookings" and is often overlooked.

> **Note:** Cliniko's built-in booking widget may show availability even without this step, but Intavia requires explicit assignments to access availability via the API.

**Fix (most likely):**

1. Go to **Settings** → **Appointment Types**
2. Click on each appointment type you want Intavia to offer
3. Scroll to the **Practitioners** section
4. Check the boxes for practitioners who can provide this service
5. **Save**

**Full checklist:**

* [ ] Appointment type is assigned to the practitioner (most common issue!)
* [ ] Online bookings are enabled globally (Settings → Appointments → Online bookings)
* [ ] Business has "Show in Online Bookings" enabled
* [ ] Practitioner has "Show in Online Bookings" enabled
* [ ] Appointment type has "Show in Online Bookings" enabled
* [ ] Daily availabilities are configured for the practitioner

### Only 1-2 slots showing per day (limited availability)

Cliniko has a setting that limits how many slots are shown per "day segment" (morning, afternoon, evening).

**Symptoms:**

* You expect full 9-5 availability but only see 1-2 slots per day
* Slots are spaced out (e.g., one at 9am, one at 12pm)

**Fix:**

1. Go to **Settings** → **Appointments** → **Online bookings**
2. Find **"Maximum available appointments per day segment"**
3. Change from `1` or `2` to **`Unlimited`** (or a higher number like `5`)
4. Save

**Why this happens:** Cliniko divides the day into segments:

* **Morning:** Before 12:00 (midday)
* **Afternoon:** 12:00 - 17:00
* **Evening:** After 17:00

If set to "1", you'll only see 1 slot per segment — so a 9-5 schedule would show just 2 slots (1 morning + 1 afternoon). The Cliniko API respects this setting, so Intavia can only see what Cliniko exposes.

### "Could not connect to Cliniko" error

Network issue or Cliniko is down.

**Fix:** Wait a few minutes and try again. Check [Cliniko Status](https://status.cliniko.com/) for outages.

***

## Cliniko Regions

Your Cliniko URL tells you which region you're on:

| URL Pattern         | Region Code    |
| ------------------- | -------------- |
| `*.au1.cliniko.com` | Australia 1    |
| `*.au2.cliniko.com` | Australia 2    |
| `*.uk1.cliniko.com` | United Kingdom |
| `*.us1.cliniko.com` | United States  |
| `*.ca1.cliniko.com` | Canada         |
| `*.eu1.cliniko.com` | Europe         |

The API key automatically includes your region (e.g., `-eu1`), so you don't need to select it manually.

***

## Security

* **Use a dedicated Scheduler user** — Don't use an Administrator account for integrations
* **Never share your API key** publicly

***

## References

* [Cliniko API Documentation](https://docs.api.cliniko.com/)
* [User Security Roles](https://help.cliniko.com/en/articles/1087327-user-security-roles) — What each role can access
* [Add a User to Cliniko](https://help.cliniko.com/en/articles/1087380-add-a-user-to-cliniko)
* [Generate a Cliniko API Key](https://help.cliniko.com/en/articles/1023957-generate-a-cliniko-api-key)
* [Cliniko Status Page](https://status.cliniko.com/)

***

*Last Updated: January 2026*