​

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 availability and booking. Cliniko does not support “any practitioner” pooled availability in our integration, so the agent must confirm a specific practitioner before it can check times.
• 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
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 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 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 for outages.

---

​

Cliniko Regions

Your Cliniko URL tells you which region you’re on: 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
• User Security Roles — What each role can access
• Add a User to Cliniko
• Generate a Cliniko API Key
• Cliniko Status Page

---

Last Updated: January 2026