How to Create an Appointment Using the Cliniko API

What the Cliniko API does and who uses it

The Cliniko API is a set of tools that lets software developers build custom systems to talk to Cliniko, a practice management platform used by health and wellness clinics. If you're a developer or work with one, you can use the API to create appointments in Cliniko from outside the Cliniko interface — from your own website, app, or booking system.

This is different from booking an appointment directly in Cliniko itself. You're writing code that sends appointment data to Cliniko's servers, which then stores it in your clinic's account. The API handles the technical handshake between your system and Cliniko's.

Most practices don't need to do this. You use it when your clinic runs a custom booking flow, integrates Cliniko with other software, or wants to automate appointment creation from a third-party system.

Key Takeaways

• You need a Cliniko account with API access enabled, and you must generate an API key from your account settings before you can make any requests.
• The API endpoint for creating appointments is a POST request to https://api.cliniko.com/v1/appointments, and it requires specific fields like practitioner ID, patient ID, appointment type ID, start time, and end time.
• Times must be sent in ISO 8601 format (for example, 2025-03-15T14:30:00Z) and must fall within your clinic's business hours and available appointment slots.
• The API returns a response that tells you whether the appointment was created successfully or what went wrong — common errors include missing required fields, invalid IDs, or time conflicts.
• Testing your code in Cliniko's sandbox environment before sending real appointment data to your live clinic account prevents mistakes from reaching your patients.

Setting up API access in your Cliniko account

Before you or a developer can create appointments via the API, you must turn on API access in Cliniko and generate an API key. Log into your Cliniko account as an administrator, go to Settings, then look for the API section. Cliniko will show you an option to generate a new API key — this is a long string of characters that acts as your password for API requests.

Store this key securely and never share it publicly or commit it to version control. If someone gets your API key, they can create, read, or modify appointments in your clinic account. If you suspect your key has been compromised, regenerate it immediately from the same settings page, which will disable the old one.

You also need to know your Cliniko account ID (sometimes called your business ID), which appears in your account settings. The developer building the integration will need both the API key and your account ID to authenticate requests.

The required fields for a POST request

When you send a request to create an appointment, you must include certain pieces of information. The request goes to https://api.cliniko.com/v1/appointments with the method POST, and the body must contain JSON data.

The required fields are:

• practitioner_id — the ID of the clinician who will see the patient. You can find this in your Cliniko account under Practitioners.
• patient_id — the ID of the patient booking the appointment. The patient must already exist in your Cliniko account.
• appointment_type_id — the ID of the appointment type (for example, "Initial Consultation" or "Follow-up"). This determines the default duration and other settings.
• start_time — when the appointment begins, in ISO 8601 format (example: 2025-03-15T14:30:00Z).
• end_time — when the appointment ends, also in ISO 8601 format.

Optional fields include notes, a custom duration, and links to other records. The Cliniko API documentation lists all available fields and their formats.

Formatting times correctly in ISO 8601

Times must be sent in ISO 8601 format, which looks like this: 2025-03-15T14:30:00Z. The Z at the end means UTC (Coordinated Universal Time). If your clinic is in a different timezone, you still send UTC time, and Cliniko converts it to your local timezone when it displays the appointment.

For example, if your clinic is in Eastern Time and you want to book a 2:30 PM appointment on March 15, 2025, you calculate the UTC equivalent (which would be 6:30 PM UTC in March, because Eastern Time is UTC-4 during daylight saving). You send 2025-03-15T18:30:00Z.

Many programming languages have libraries that handle this conversion automatically. In JavaScript, Python, or PHP, you can use built-in date functions to convert local time to ISO 8601 without doing the math yourself. The Cliniko API documentation includes examples in several languages.

Validating the appointment against clinic availability

The API will reject an appointment if it conflicts with your clinic's schedule or settings. Common reasons for rejection are:

• The start and end times fall outside your clinic's business hours.
• The practitioner is not available at that time (they have another appointment, are marked as unavailable, or don't work that day).
• The appointment type is not assigned to that practitioner.
• The patient or practitioner IDs don't exist in your account.
• The start time is in the past.

When the API rejects a request, it returns an error message that usually tells you which field caused the problem. Read the error carefully — it often points to the exact issue. If the error message is unclear, check that the IDs are correct and that the times fall within your clinic's actual availability.

Handling the API response

When you send a POST request to create an appointment, Cliniko sends back a response. If the appointment was created successfully, the response includes a 201 status code and returns the full appointment object, including the appointment ID that Cliniko assigned to it. Store this ID if you need to reference the appointment later.

If something went wrong, you'll get a 4xx or 5xx status code. A 400 error usually means your request was malformed (missing fields, wrong format, or invalid data). A 401 error means your API key is missing or invalid. A 409 error usually means there's a conflict — for example, the time slot is already booked.

Always check the status code and read the error message before assuming the appointment was created. In production code, you should log the response and alert the user if the appointment creation failed, rather than silently moving forward.

Testing in the sandbox before going live

Cliniko provides a sandbox environment where you can test your API code without affecting your real clinic data. Use the sandbox URL and a sandbox API key to develop and test your integration. This lets you make mistakes, test edge cases, and verify that your code works correctly before you point it at your live clinic account.

Once you're confident the code works, switch to your production API key and the live Cliniko URL. Even then, test with a small number of real appointments first and watch for errors before rolling it out to all your booking channels.

Frequently Asked Questions

Do I need a developer to use the Cliniko API?

Yes. The API is a technical tool designed for software developers. If you want to integrate Cliniko with another system or build a custom booking interface, you'll need someone who can write code. Cliniko's support team can point you to integrations that are already built, which may not require custom development.

Can I create a patient and an appointment in one API call?

No. The patient must already exist in your Cliniko account before you create an appointment for them. You can use the API to create a patient first (via the patients endpoint), then create the appointment. Some integrations do this in sequence automatically.

What happens if I send the same appointment request twice by mistake?

Cliniko will create two separate appointments. The API doesn't have built-in duplicate detection, so if your code sends the same request twice, you'll end up with two bookings. To prevent this, your code should check whether an appointment already exists before sending the request, or use a unique reference ID to track requests.

Can the API send appointment reminders or confirmations?

The API creates the appointment, but reminder and confirmation emails are handled by Cliniko's built-in automation. Once the appointment is created via the API, Cliniko's rules apply — if you have reminders turned on for that appointment type, Cliniko will send them automatically.

How do I find the IDs I need to include in the request?

Log into your Cliniko account and navigate to the relevant section: Practitioners to find practitioner IDs, Patients to find patient IDs, and Settings > Appointment Types to find appointment type IDs. The Cliniko API also includes endpoints that let you retrieve these IDs programmatically, so your code can look them up instead of hardcoding them.