How to Create an Appointment in Cliniko Using the API

What the Cliniko API does and why you'd use it

The Cliniko API lets you build your own software or connect other tools to Cliniko's appointment system. Instead of manually entering each appointment into Cliniko, you can send appointment data from another program—a website booking form, a phone system, a payment app, or your own custom software—and Cliniko creates the appointment automatically.

This is useful if you run a practice management system that isn't Cliniko, or if you want to let clients book directly from your website without logging into Cliniko itself. The API handles the technical connection between your system and Cliniko's database.

You do not need to use the API to create appointments in Cliniko. The standard way is to log into Cliniko and enter them by hand, or to import a spreadsheet. The API is for people who want to automate the process or integrate Cliniko with other software they already use.

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, and start time.
• Cliniko's API documentation lists all required and optional fields, and the API will reject requests that are missing required data or have incorrectly formatted information.
• You will need to know the IDs of your practitioners, patients, appointment types, and business (location), which you can retrieve through separate API calls if you don't already have them.
• Most errors come from missing required fields, incorrect date-time formatting, or using IDs that don't exist in your Cliniko account.

Getting API access and generating your key

Log into your Cliniko account and go to Settings. Look for the API section—this is usually under Account Settings or Developer Settings, depending on your Cliniko plan. Not all plans include API access; if you don't see an API section, you may need to upgrade or contact Cliniko support to enable it.

Once you find the API section, you'll see an option to generate an API key. Click it, and Cliniko will create a long string of characters. Copy this key and store it somewhere secure—you'll need it for every API request, and anyone with this key can create, read, or modify data in your Cliniko account. Do not share it or paste it into public code repositories.

If you lose the key, you can generate a new one from the same settings page. The old key will stop working immediately.

The basic structure of an appointment creation request

An API request to create an appointment is a POST request sent to https://api.cliniko.com/v1/appointments. The request must include your API key in the header, and the appointment data in the body.

The body is formatted as JSON, which is a standard way of sending structured data. At minimum, you must include:

• Practitioner ID (the staff member running the appointment)
• Patient ID (the person coming in)
• Appointment type ID (the service being booked)
• Start time (in ISO 8601 format: YYYY-MM-DDTHH:MM:SS)

Optional fields include end time, notes, and custom fields specific to your practice. If you don't specify an end time, Cliniko will calculate it based on the appointment type's default duration.

Here's a simplified example of what the JSON body looks like:

{ "appointments": { "practitioner_id": "12345", "patient_id": "67890", "appointment_type_id": "11111", "starts_at": "2024-03-15T14:00:00" } }

The exact field names and structure are defined in Cliniko's API documentation. If you send a request with the wrong field names or missing required fields, the API will return an error message telling you what's wrong.

Finding the IDs you need

Before you can create an appointment, you need the numeric IDs for your practitioners, patients, appointment types, and business location. These are not the names—they're the unique identifiers Cliniko assigns to each item.

You can find these IDs in two ways. The first is to log into Cliniko and look at the URL or the settings page for each item. For example, if you click on a practitioner's profile, the URL might show cliniko.com/practitioners/12345—that number is the practitioner ID.

The second way is to use the API itself to retrieve a list of all practitioners, patients, or appointment types in your account. This requires separate GET requests to endpoints like https://api.cliniko.com/v1/practitioners or https://api.cliniko.com/v1/patients. These requests will return all the data for each item, including the ID.

If you're building a booking form or integration, you'll usually retrieve these lists once and store them, so you don't have to call the API every time someone wants to book.

Common errors and what causes them

Missing required fields: If you don't include practitioner ID, patient ID, appointment type ID, or start time, the API will reject the request with a 422 error. Double-check that all four are present and are numbers, not text.

Incorrect date-time format: The start time must be in ISO 8601 format (YYYY-MM-DDTHH:MM:SS). If you send "3/15/2024 2:00 PM" or any other format, the API will reject it. Make sure your code converts times to the correct format before sending.

IDs that don't exist: If you use a practitioner ID or patient ID that isn't in your Cliniko account, the API will return a 404 error. Verify that the IDs are correct and that the practitioner or patient actually exists in your account.

Scheduling conflicts: If the time slot is already booked, Cliniko may reject the request or create the appointment anyway, depending on your settings. Check Cliniko's documentation for how your account handles overlapping appointments.

Authentication errors: If your API key is missing, expired, or incorrect, the API will return a 401 error. Make sure you're including the key in the request header and that it hasn't been regenerated or revoked.

Testing your request before going live

Before you integrate the API into your main booking system, test it with a simple tool. Postman is a free application that lets you send API requests without writing code. You can paste your endpoint URL, add your API key to the headers, paste your JSON body, and click Send to see what Cliniko returns.

Start by creating a test appointment with a real practitioner and patient ID from your Cliniko account. If the request succeeds, you'll get a 201 response and Cliniko will return the full appointment data, including the appointment ID it just created. Log into Cliniko and verify that the appointment appears on the calendar.

If you get an error, Cliniko's response will tell you what's wrong. Fix the issue and try again. Once you have a working request, you can translate it into code in whatever programming language your system uses.

Integrating the API into your booking system

Once you've tested a basic request, you can build it into your website, app, or other software. Most programming languages have libraries that make API requests easier—for example, Python has the requests library, JavaScript has fetch, and PHP has curl.

Your code will typically do this: take the appointment details from a form or database, format them as JSON, add your API key to the headers, send a POST request to Cliniko, and then handle the response. If Cliniko returns a success code (201), the appointment is created. If it returns an error, your code should show the error message to the user or log it for debugging.

Keep your API key secure. Never hardcode it into client-side code (like JavaScript that runs in a browser). Instead, store it on your server and have your server make the API request on behalf of the client.

Frequently Asked Questions

Do I need to use the API, or can I just enter appointments manually in Cliniko?

You can enter appointments manually through Cliniko's web interface. The API is only necessary if you want to automate the process or connect Cliniko to another system. Most small practices don't use the API.

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

Cliniko will create two separate appointments. The API doesn't check for duplicates. If you're building an automated system, add logic on your end to prevent the same request from being sent twice, or check whether the appointment already exists before creating it.

Can I update or cancel an appointment through the API?

Yes. The API supports PUT requests to update an existing appointment and DELETE requests to cancel one. You'll need the appointment ID, which Cliniko returns when you create the appointment. Cliniko's API documentation covers the exact fields you can update.

What if my patient or practitioner doesn't exist in Cliniko yet?

You must create the patient and practitioner first, either manually in Cliniko or through separate API calls. The appointment creation endpoint requires IDs that already exist. You cannot create a patient or practitioner as part of the appointment request.

How do I know if my API key is working?

Send a simple GET request to https://api.cliniko.com/v1/practitioners with your API key in the header. If the key is valid, Cliniko will return a list of your practitioners. If it's invalid or missing, you'll get a 401 error.