HomeGuidesAPI Reference
Log In

Create an appointment using the API

This developer documentation explains our data model and introduces you to our playground.


Creating an appointment is the most important flow on the Ally Health platform. Using this API you can integrate all operational tasks to create and manage clinically controlled appointments into your own software. For example this service can be integrated into your e-commerce checkout journey for booking at home phlebotomy for a blood test, or into a practice management solution to enable a range of on-demand post-op tasks such as suture removal or wound dressing changes.

The overall approach to creating your first appointment is:

  1. Create a Patient
  2. Choose a care task
  3. Check availability
  4. Create an Appointment

Test Mode

Try out making API requests with Test Mode enabled as these will never create a real care task. To be sure you are making test requests to our system, you should only use API keys that start with "test_"

Data Model

Take your time to familiarise yourself with our terminology to get a quick understanding of our data model

Step-by-step Guide

Pre-requisitesBefore starting you must register on the Ally Heath platform, and verify your email address. Please note that at this time we are in private Beta mode so only approved email addresses can sign-up
Login to docsNavigate to docs.allyhealth.co.uk and click login in the top right corner. Once you have logged in, you should see your name replace the login button
Create a patientNavigate to Create patient, and enter the required fields (highlighted in red). Click "Try it!" button
Take note of the patientIdThe API will return the id of the patient that was just created. The id will look like "p_jhOUWehwefiwuef." Please note down the id for use later
Choose a care taskUse the Get tasks interface to see a list of available care tasks on the system. Take note of one of the taskId's which is in the format "tsk_liuweruhsfd"
Check availabilityUse the Get availability interface to check the availability to perform an availability check for a given postcode. Enter a postcode and the taskId from the previous step, and click "Try It". Make a note of the postcode that you used
Take note of the windowIdReview the returned availability, and choose a time window when you want the appointment to happen. Take a note of the windowId for the time window that you want
Create an appointmentYou will now use the patientId, taskId and windowId to create an appointment. Navigate to Create appointment, and fill in this information, as well as to input the location for the appointment using the same postcode that you used for the availability check. Click "Try It"
Review your appointmentIf all is successful, you will see an appointmentId returned. You can visit the appointments tab in the dashboard to see your scheduled appointment

Frequently Asked Questions

Where can appointments take place?
Appointments can take place in any location in our coverage area, which is currently covers 75% of the United Kingdom population.