Booking Appointments

This guide outlines best practices for creating appointment records with the ezyVet API.

Overview

Use the /ezycab/booking endpoint to create appointments. This endpoint:

• Creates and links a consult record automatically
• Applies any billing triggers associated with the Appointment type

For those reasons, /ezycab/booking is the preferred endpoint for creating appointments over /v2/appointment.

Best practice workflow

1. Confirm time zone and site context
   • Call v3/siteInformation and store the site id and timezone.
2. Load appointment types and resources
   • Call v2/appointmenttype and store the appointment type uid.
   • Call v2/resource and store the resource uid.
3. Check availability
   • Call /availability with the appointment type, resource, and target time range.
   • Optionally call /ezycab/v2.1/planning-guides to retrieve the resource's availability windows (the scheduling blocks that define when a resource is open for bookings). This is useful for integrations that maintain a local copy of resource availability rather than querying /availability for every slot.
4. Create the booking
   • Call /ezycab/booking with the confirmed slot, appointment type, resource, animal, and contact.
5. Persist the linked records
   • Store the appointment uid returned by the booking response.

Why not create appointments via /v2/appointment?

Creating a record via /v2/appointment only creates the appointment itself. It does not:

• Create the consult record
• Apply billing triggers tied to the Appointment type

If you need a consult and billing triggers created, /ezycab/booking is the correct endpoint.

Data to include in a booking request

At minimum, ensure the booking request includes:

• Start time and duration
• Appointment type uid
• Animal and contact identifiers
• Resource uid as provider

Facility / system user bookings

A facility / system user is a provider resource that is not tied to a specific human practitioner (resource type of facility). Because these users cannot be linked to records with a financial impact on the clinic, bookings against them follow a reduced path:

Appointment record: created as normal.

Default billing triggers: not applied. The appointment type's default billing triggers are skipped; no billing items are attached.

Clinical record (consult): created only when the appointment type has isConsultRequired = true. If the appointment type does not require a consult, no consult is created.

For non-facility (human-backed) provider resources the existing behaviour is unchanged.

Behavioural matrix

Provider resource type	appointmentType.isConsultRequired	Appointment	Billing triggers	Consult
Non-facility (human)	true	Created	Applied	Created
Non-facility (human)	false	Created	Applied	Not created
facility (system user)	true	Created	Not applied	Created
facility (system user)	false	Created	Not applied	Not created

Example flow (high level)

1. Load appointment types and resources.
2. Query /availability for a bookable slot.
3. Create the appointment via /ezycab/booking.
4. Use the returned consult record for clinical work.
5. Allow billing triggers to populate the appropriate billing items.

Relevant endpoints

• /ezycab/availability - Get bookable appointment slots
• /ezycab/v2.1/planning-guides - Get resource availability windows (planning guides)
• /ezycab/booking - Create appointments with consult + billing triggers
• v2/appointmenttype - Get appointment types
• v2/resource - Get resources
• v3/siteInformation - Get timezone info
• v2/contact - Get contact info
• v2/animal - Get animal info