Calendar Management

Calendar is where all appointments and actions are created, assigned and scheduled.

Availability is also managed here, this is an assignment of a practitioner's schedule for appointment booking.

Calendar in Merlin?

Calendar is referred to as 'Diary' in Merlin, however not all elements of Merlin's diary are found in this domain, such as practitioners which are found under the contact management domain.

Relationships

The calendar domain has several entities, prominently being appointments which are referenced to in clinical work.

Appointments when being made use the whole availability slot(s), however there are no direct identifiers for slots or association between availability and appointments. Availability is used as a business rule to assign and align schedules.

Task lists (for example Hospital or Repeat Prescription columns on the diary Day view) are also part of this domain. They use a separate capacity model from timed practitioner appointments; see Task lists and capacity below.

Diary mode (Practitioner and Room)

Merlin can run the diary in one of two modes at site level. The mode affects which contacts may be used as the diary column, how availability is interpreted, and which validations apply on create and update operations. The OpenAPI spec exposes the extra fields and error responses; behaviour is aligned with Merlin’s diary.

Mode	Status	Diary columns	Typical use
Practitioner	Default (existing behaviour)	People (practitioners / vets)	Appointments are booked against a practitioner’s column.
Room	Beta (trial in selected practices)	Rooms (for example theatres, consult rooms)	The column is a room; the vet doing the work is carried on the appointment separately.

Room mode is a beta capability

Room mode is being introduced gradually. Most practices remain on Practitioner mode. How to tell which mode applies from API responses (including availability) is described in How the API represents the two modes below.

How the API represents the two modes

Practitioner mode

• Contact practitioner on an appointment or availability is a person (practitioner-type PRACTITIONER on responses where exposed).
• Available slots identify the practitioner on the slot.
• Create and update operations reject room contacts where only a human practitioner is valid for that site’s mode.

Room mode

• Contact practitioner is the room (the diary column) — practitioner-type ROOM.
• Assigned practitioner is the person who will perform the work. The assigned contact must be a practitioner, not a room (assigned-practitioner-type PRACTITIONER).
• GET /availability/{location-uuid}/available returns room-oriented fields on each slot, including practitioner-type, practitioner-name, practitioner-uuid-for-room, and practitioner-name-for-room.
• Creating availability may include practitioner-uuid-for-room on the request where the room block is linked to a vet for that period.

Appointment and availability responses can include contact-practitioner-type, contact-practitioner-name, assigned-practitioner-type, and assigned-practitioner-name so clients can display column and assignee without inferring from legacy labels.

Availability tags (empty-slot-text)

Optional empty-slot-text (up to 50 characters) can appear on GET /availability/{location-uuid}/available slots and on POST /availability when creating availability. This is the API representation of Merlin availability tagging.

Example: booking in Room mode

A site runs Room mode. Reception finds a slot for room Theatre 1; the available-slot payload shows practitioner-type ROOM and practitioner-name-for-room Dr Adebayo.

They POST /appointments with:

• Contact practitioner = Theatre 1’s room contact UUID (the column).
• Assigned practitioner = Dr Adebayo’s practitioner UUID.

The created appointment response includes the type and name fields for both contacts.

Example: integration that only supports people

On any site, GET /practitioners in the contact domain supports exclude-rooms=true to omit rooms (practitioner-type ROOM) from practitioner pickers. On Practitioner mode sites, rooms are not valid diary columns for practitioner appointments; validation errors are returned if a room UUID is used where a person is required.

Room-specific directory fields (practitioner-type-name, exclude-rooms, and related practitioner-location metadata) are documented under Practitioners and rooms in the contact domain.

Task lists and capacity

Task lists are untimed diary columns (task-list practitioners). Merlin’s Day view shows a number of blank slots plus every booked task for that day. Historically the blank pool was effectively capped at 50 per list; practices can now configure Number of slots per task list per site (range 1–50, default 50), matching Merlin's UI.

The API exposes and enforces the same limits as Merlin’s diary and Send To flows.

Reading capacity

GET /task-lists/locations returns task-list placements at locations. Each row includes number-of-slots: the configured maximum number of tasks that may exist for that task list at that location on a given calendar day (before considering how many are already booked).

Use this value when building booking UI or pre-checking whether another task can be added.

Creating tasks at capacity

POST /tasks counts existing tasks for the requested task list, location, and task date. If bookings already fill the configured limit, the request is rejected with 422 (for example when five slots are configured and five tasks already exist for that date).

Rules match Merlin:

Situation	API behaviour
Bookings below number-of-slots	Create succeeds if other validations pass.
Bookings equal to number-of-slots	Create rejected — no free capacity.
Bookings above number-of-slots (limit lowered after bookings were made)	Existing tasks remain; new creates are rejected until the count drops below the limit.

Example

1. GET /task-lists/locations shows Hospital at Main site with "number-of-slots": 5.
2. Five tasks already exist for Hospital at Main on the requested date.
3. POST /tasks for another task on that date returns 422 — the list is full for that day.

Related Limitations

1. An appointment being created or updated, must use the entire availability slot (or multiple slots).
2. Appointment using more than 1 availability slot, must be sequential in time.
3. An appointment cannot be assigned more than 1 practitioner, therefore multiple availability slots must be sequencial for the same practitioner.

---

Calendar Schema

Please take note of the following points for this schema:

1. Appointment Start + End Date must be within the same day.
2. Appointment Reason Text supplied overwrites the reason-uuid selected.
3. Contact practitioner is the diary column the appointment is booked under — a practitioner in Practitioner mode, or a room in Room mode. See Diary mode (Practitioner and Room).
4. Assigned practitioner is the person assigned to do the work without moving the appointment on the diary. In Room mode this is required to be a person, not a room; it overrides contact practitioner for display in Merlin.
5. Appointment Online Booking field helps identify to a user that the appointment was booked via a self-serve portal.

Cross Domain UUID References

Reference	Domain	Resource	Note
account-uuid	account-management	/accounts	Identifies which account the appointment was booked for.
account-contact-uuid	contact-management	/contacts	Identifies the Contact who will be attending the appointment, e.g. Pet Owner. This specificially needs to be a contact associated with the account.
patient-uuid	patient-management	/patients	Identifies the specific patient this appointment is for under the account.
location-uuid	location-management	/locations	Identifies the pratice location the appointment will be located/arranged under.
contact-practioner-uuid	contact-management	/contacts, /practitioners	Identifies the Practitioner for the appointment (2 entities of practitioner-uuid on the same object therefore practitioner-uuid is prefixed.)
assigned-practitioner-uuid	contact-management	//contacts, /practitioners	Identifies the Practitioner the appointment has been assigned to (practitioner-uuid with prefix)
practioner-uuid	contact-management	/contacts, /practitioners	Identifies the Practitioner (no prefix)

Security Scopes

The following authorisation scopes are required to access different resources within this domain:

• calendar:appointment:read
• calendar:appointment:create
• calendar:appointment:update
• calendar:appointment:remove
• calendar:availability:read
• calendar:availability:create
• calendar:availability:update
• calendar:availability:remove