{ "openapi": "3.0.1", "info": { "title": "ezyVet API", "description": "Welcome to the ezyVet API Documentation Page!\n\nThe ezyVet API (API moving forward) is designed around a RESTful interface and utilizes OAuth 2.0 Client Credentials grant. \n\nThe API accepts URL params and JSON-formatted requests, and returns JSON-formatted responses.\n", "version": "1.0" }, "servers": [ { "url": "https://api.ezyvet.com", "description": "ezyVet production environment" }, { "url": "https://api.trial.ezyvet.com", "description": "ezyVet trial environment" } ], "security": [], "tags": [ { "name": "Appointment", "description": "Handles scheduling and management of appointments for veterinary services." }, { "name": "Appointment V2", "description": "An updated version of appointment management with enhanced features and additional data fields." }, { "name": "Planning Guides", "description": "Planning guide sync endpoints designed for integrations that maintain a local copy of resource availability windows." }, { "name": "Appointment Booking", "description": "Creates appointment bookings, with their associated consultation and billing triggers." }, { "name": "Appointment Status", "description": "Manages the status of appointments (e.g., scheduled, completed, canceled)." }, { "name": "Appointment Type", "description": "Defines types of appointments (e.g., check-up, surgery, vaccination)." }, { "name": "Appointment Type V2", "description": "An updated version of appointment type management with additional options and refinements." }, { "name": "Availability", "description": "Manages resource or staff availability for scheduling purposes." }, { "name": "Resource", "description": "Manages clinic resources, such as staff, rooms, or equipment, for scheduling." }, { "name": "Resource V2", "description": "An updated version of resource management with additional functionality." }, { "name": "Shelter Animal Booking", "description": "Manages bookings or records for shelter animals within the clinic." } ], "components": { "securitySchemes": { "bearerAuth": { "type": "oauth2", "flows": { "clientCredentials": { "tokenUrl": "https://api.ezyvet.com/v1/oauth/access_token", "scopes": { "create-booking": "Create booking resources", "read-appointment": "Read appointment resources", "read-appointmentstatus": "Read appointment status resources", "read-appointmenttype": "Read appointment type resources", "read-resource": "Read resource resources", "read-shelteranimalbooking": "Read shelter animal booking resources", "write-appointment": "Create and update appointment resources" } } } } }, "responses": { "BadRequest": { "description": "Bad Request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BadRequest" } } } }, "InternalError": { "description": "Internal error", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "error_5JBMuXC69QQoPpKDFoBow" }, "status": { "type": "string", "example": "500" }, "code": { "type": "string", "example": "" }, "title": { "type": "string", "example": "An internal server error occurred" }, "detail": { "type": "string", "example": "An error occured, please contact API support with the id, status and code provided with the response." } } } } } }, "NotFound": { "description": "Not Found", "content": { "text/html": { "schema": { "type": "string", "example": "No input file specified." } } } }, "TooManyRequests": { "description": "Too Many Requests", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "error_5JBMuXC69QQoPpKDFoBow" }, "status": { "type": "string", "example": "429" }, "code": { "type": "string", "example": "" }, "title": { "type": "string", "example": "Too Many Requests" }, "detail": { "type": "string", "example": "Too Many Requests" } } } } } }, "Unauthorized": { "description": "Unauthorized", "content": { "application/json": { "schema": { "type": "object", "properties": { "messages": { "type": "array", "items": { "properties": { "level": { "type": "string", "example": "error" }, "type": { "type": "string", "example": "InvalidRequestException" }, "text": { "type": "string", "example": "The request is missing a required parameter, includes an invalid parameter value, includes a parameter more than once, or is otherwise malformed. Check the \\\"access token\\\" parameter." }, "fields": { "type": "array", "example": [], "items": { "type": "string" } } } } } } } } } }, "UnprocessableEntity": { "description": "Unprocessable Entity", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "string", "example": "error_5JBMuXC69QQoPpKDFoBow" }, "status": { "type": "string", "example": "422" }, "code": { "type": "string", "example": "" }, "title": { "type": "string", "example": "Unprocessable Entity" }, "detail": { "type": "string", "example": "Unprocessable Entity" } } } } } } }, "schemas": { "AppointmentRecurrence": { "type": "object", "description": "Recurrence metadata. Present when the appointment belongs to a recurring series.", "properties": { "repeat_interval": { "type": "integer", "description": "How often the series repeats, in seconds. Always a multiple of 604800 (1 week). For example: 604800 = weekly, 1209600 = every 2 weeks.\n", "example": 604800 }, "repeat_end_at": { "type": "integer", "nullable": true, "description": "Epoch time for when the recurring series ends. Null means the series has no defined end and repeats indefinitely.\n", "example": 1798761600 } } }, "AppointmentsV21Meta": { "type": "object", "properties": { "nextToken": { "type": "string", "nullable": true, "description": "Cursor for the next page. Pass as `nextToken` on the next request. Absent or null when there are no further pages.\n", "example": "AB3e7Z2i9FJu0j7hLExLp" } } }, "AppointmentTypeReference": { "type": "object", "required": [ "type", "id" ], "properties": { "type": { "type": "string", "enum": [ "appointmentType" ], "example": "appointmentType" }, "id": { "type": "string", "pattern": "^appointmentType_[a-zA-Z0-9]{21}$", "description": "Unique identifier for the appointment type", "example": "appointmentType_UuUSqzZE1RwAAS68oj1BF" } } }, "AppointmentV21": { "type": "object", "description": "An appointment record. Fields are consistent with the v2 appointment endpoint. Net-new additions in v2.1: `uid`, `type_uid`, `animal_uid`, `contact_uid`, and `recurrence`.\n", "properties": { "id": { "type": "integer", "description": "Numeric identifier for the appointment.", "example": 12345 }, "uid": { "type": "string", "description": "Globally unique string identifier for the appointment.", "example": "appointment_X8CLo8J3gEBtRbykwia6q" }, "created_at": { "type": "integer", "description": "Epoch time when the appointment was created.", "example": 1307498299 }, "modified_at": { "type": "integer", "description": "Epoch time when the appointment was last modified.", "example": 1765395429 }, "active": { "type": "boolean", "description": "Whether the appointment is active. A value of `false` means the appointment has been cancelled or deleted — sync integrations should remove it from their local copy.\n", "example": true }, "start_at": { "type": "integer", "description": "Epoch time when the appointment starts.", "example": 1307491200 }, "duration": { "type": "integer", "description": "Duration of the appointment in seconds.", "example": 2400 }, "type_id": { "type": "integer", "description": "Numeric ID of the AppointmentType.", "example": 1 }, "type_uid": { "type": "string", "description": "Globally unique string identifier of the AppointmentType.", "example": "appointmentType_jemy7oGJjj0BExij6D3xk" }, "status_id": { "type": "integer", "description": "Numeric ID of the AppointmentStatus.", "example": 1 }, "status_uid": { "type": "string", "description": "Globally unique string identifier of the AppointmentStatus.", "example": "appointmentStatus_1N3r94lmYh5okkql6jeGF" }, "description": { "type": "string", "description": "Free-text appointment notes.", "example": "Annual checkup" }, "animal_id": { "type": "integer", "nullable": true, "description": "Numeric ID of the animal, or null if not set.", "example": 9 }, "animal_uid": { "type": "string", "nullable": true, "description": "Globally unique string identifier of the animal, or null if not set.", "example": "animal_HeXPdBCykd60T8NrhKPoj" }, "consult_id": { "type": "integer", "nullable": true, "description": "Numeric ID of the consult, or null if not yet created.", "example": 6862 }, "consult_uid": { "type": "string", "nullable": true, "description": "Globally unique string identifier of the consult, or null if not yet created.", "example": "consult_jPdsIZXQaGxoLGnVy5CXi" }, "contact_id": { "type": "integer", "nullable": true, "description": "Numeric ID of the contact (client), or null if not set.", "example": 14 }, "contact_uid": { "type": "string", "nullable": true, "description": "Globally unique string identifier of the contact, or null if not set.", "example": "contact_ATplEuzOYEWqmfQ95sMZJ" }, "sales_resource": { "type": "integer", "nullable": true, "description": "Numeric ID of the primary SalesResource allocated to this appointment.", "example": 1932 }, "sales_resource_uid": { "type": "string", "nullable": true, "description": "Globally unique string identifier of the primary SalesResource allocated to this appointment.", "example": "resource_dC7T87I3VNJbcttDAeeID" }, "event_group": { "type": "integer", "nullable": true, "description": "ID of the event group this appointment belongs to, if any.", "example": 36 }, "destination_address": { "type": "integer", "nullable": true, "description": "ID of the destination address for mobile/house-call appointments. 0 if not set.", "example": 0 }, "resources": { "type": "array", "description": "All resources (staff and facilities) allocated to this appointment. Each entry includes a `type` field (`user` or `facility`) to distinguish between clinical staff and rooms/equipment.\n", "items": { "$ref": "#/components/schemas/ResourceItem" } }, "cancellation_reason": { "type": "string", "nullable": true, "description": "Reason code for cancellation, or null if not cancelled.", "example": null }, "cancellation_reason_text": { "type": "string", "nullable": true, "description": "Free-text cancellation note, or null if not cancelled.", "example": null }, "recurrence": { "nullable": true, "description": "Recurrence metadata for this appointment. `null` for one-time appointments. `repeat_interval` is always a multiple of 604800 (1 week). `repeat_end_at` is `null` when the series repeats indefinitely.\n", "allOf": [ { "$ref": "#/components/schemas/AppointmentRecurrence" } ] } } }, "Availability": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "resourceAvailability_xOjIwMjMtMDktMjcfgf" }, "type": { "type": "string", "example": "resourceAvailability" }, "attributes": { "type": "object", "properties": { "date": { "type": "string", "example": "2024-06-09" }, "timezone": { "type": "string", "example": "Pacific/Auckland" }, "slots": { "$ref": "#/components/schemas/AvailabilitySlots" } } }, "relationships": { "type": "object", "properties": { "site": { "type": "object", "properties": { "id": { "type": "string", "example": "site_HIrgCIDevelopmentSite" }, "type": { "type": "string", "example": "site" } } }, "resource": { "type": "object", "properties": { "id": { "type": "string", "example": "resource_06LfqGFlTXo249hhmPZfk" }, "type": { "type": "string", "example": "resource" } } } } } } } } } }, "AvailabilityAttributes": { "type": "object", "required": [ "date", "timezone", "slots" ], "properties": { "date": { "type": "string", "format": "date", "description": "The date for which availability is calculated (ISO 8601 format)", "example": "2025-10-24" }, "timezone": { "type": "string", "description": "IANA timezone identifier for the site", "example": "Pacific/Auckland" }, "slots": { "type": "array", "description": "Array of time slots showing availability throughout the day", "items": { "$ref": "#/components/schemas/Slot" } } } }, "AvailabilityData": { "type": "object", "required": [ "id", "type", "attributes", "relationships" ], "properties": { "id": { "type": "string", "description": "Unique identifier for this availability record", "pattern": "^resourceAvailability_[a-zA-Z0-9]{21}$", "example": "resourceAvailability_kzezOO9OE5TRqTRWjTlDX" }, "type": { "type": "string", "description": "Resource type identifier", "enum": [ "resourceAvailability" ], "example": "resourceAvailability" }, "attributes": { "$ref": "#/components/schemas/AvailabilityAttributes" }, "relationships": { "$ref": "#/components/schemas/AvailabilityRelationships" } } }, "AvailabilityRelationships": { "type": "object", "required": [ "site", "resource" ], "properties": { "site": { "$ref": "#/components/schemas/SiteReference" }, "resource": { "$ref": "#/components/schemas/ResourceReference" } } }, "AvailabilitySlots": { "type": "array", "items": { "properties": { "start": { "type": "string", "example": "2024-06-30T00:00:00.000+12:00" }, "duration": { "type": "number", "example": 15 }, "available": { "type": "boolean", "example": true }, "relationships": { "type": "object", "properties": { "appointmentType": { "type": "object", "properties": { "data": { "type": "array", "items": { "properties": { "type": { "type": "string", "example": "appointmentType" }, "id": { "type": "string", "example": "appointmentType_hslifhr56n5j5jiudfh" } } } } } } } } } } }, "BadRequest": { "description": "Bad Request", "type": "object", "properties": { "errors": { "type": "array", "items": { "properties": { "id": { "type": "string", "example": "error_3YLvb0V7eXcHqgGauTjDy" }, "status": { "type": "string", "example": "400" }, "code": { "type": "string", "example": "100001" }, "title": { "type": "string", "example": "The authorization grant type is not supported by the authorization server." }, "detail": { "type": "string", "example": "The authorization grant type is not supported by the authorization server." } } } } } }, "BookingRequest": { "type": "object", "required": [ "startTime", "type", "animal", "contact", "provider" ], "properties": { "startTime": { "type": "string", "format": "date-time", "description": "Appointment start time in UTC with offset format; must not be in the past (e.g., 2025-07-14T09:30:00.000-04:00 or 2025-07-14T09:30:00Z).", "example": "2025-07-14T09:30:00.000-04:00" }, "type": { "type": "string", "pattern": "^appointmentType_.*$", "description": "Appointment type UID.", "example": "appointmentType_98765" }, "durationMinutes": { "type": "integer", "description": "Duration in minutes. Defaults to the appointment type’s duration, or 30 minutes if the appointment type’s duration is 0.", "example": 30 }, "appointmentStatus": { "type": "string", "enum": [ "no_status", "confirmed", "unconfirmed" ], "default": "unconfirmed", "description": "Appointment status. Defaults to unconfirmed.\nThe `no_status` value is for clinics using the SmartFlow integration who want the appointment pulled into their SmartFlow workflows.", "example": "unconfirmed" }, "description": { "type": "string", "description": "Appointment description.", "example": "Routine check-up" }, "animal": { "type": "string", "pattern": "^animal_.*$", "description": "Animal UID.", "example": "animal_f47ac10bassssdasda" }, "contact": { "type": "string", "pattern": "^contact_.*$", "description": "Contact UID.", "example": "contact_f47ac10bxcxasdoaids" }, "provider": { "type": "string", "pattern": "^resource_.*$", "description": "Primary resource UID. Refer to the Booking guide for more info on what this field impacts.", "example": "resource_0L08Ggnl7UB5AhVOys3t1" }, "additionalResources": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^resource_.*$" }, "description": "Additional resource UIDs.", "example": "resource_0L08Ggnl7UB5AhVOys3t1" } } }, "BookingResponse": { "type": "object", "properties": { "id": { "type": "string", "description": "Booking request unique identifier.", "example": "bookingRequest_123" }, "appointment": { "type": "string", "description": "Created appointment unique identifier.", "example": "appointment_asdf" } } }, "ErrorResponse": { "type": "object", "required": [ "statusCode", "message", "error" ], "properties": { "statusCode": { "type": "integer", "description": "HTTP status code", "example": 400 }, "message": { "type": "string", "description": "Human-readable error message", "example": "Invalid request parameters" }, "error": { "type": "string", "description": "Error type", "example": "Bad Request" }, "details": { "type": "object", "description": "Additional error details (optional)", "additionalProperties": true } } }, "GetAppointmentsV21Response": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/AppointmentsV21Meta" }, "data": { "type": "array", "description": "List of appointments for the current page.", "items": { "$ref": "#/components/schemas/AppointmentV21" } } } }, "GetAvailabilityResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Array of resource availability data for requested resources and dates", "items": { "$ref": "#/components/schemas/AvailabilityData" } } } }, "GetPlanningGuidesV21Response": { "type": "object", "required": [ "meta", "data" ], "properties": { "meta": { "$ref": "#/components/schemas/AppointmentsV21Meta" }, "data": { "type": "array", "description": "List of planning guides for the current page.", "items": { "$ref": "#/components/schemas/PlanningGuideV21" } } } }, "PlanningGuideV21": { "type": "object", "description": "A planning guide record (appointmentdata_calendartype = 'Guide'). Planning guides define availability windows for resources. They never have patient data (animal, contact, consult) and rarely have cancellation fields.\n", "properties": { "id": { "type": "integer", "description": "Numeric metaappointment ID.", "example": 2048 }, "uid": { "type": "string", "description": "Globally unique string identifier for the planning guide.", "example": "appointment_uJMYy7DC3CT9MsPB0r3HU" }, "created_at": { "type": "integer", "description": "Epoch time when the guide was created.", "example": 1307498299 }, "modified_at": { "type": "integer", "description": "Epoch time when the guide was last modified.", "example": 1765395429 }, "active": { "type": "boolean", "description": "Whether the guide is active. `false` means the guide has been deactivated.", "example": true }, "start_at": { "type": "integer", "description": "Epoch time when the availability window starts.", "example": 1307491200 }, "duration": { "type": "integer", "description": "Duration of the availability window in seconds.", "example": 28800 }, "type_id": { "type": "integer", "description": "Numeric ID of the AppointmentType this guide covers.", "example": 8 }, "type_uid": { "type": "string", "description": "Globally unique string identifier of the AppointmentType.", "example": "appointmentType_jemy7oGJjj0BExij6D3xk" }, "description": { "type": "string", "description": "Free-text notes on the guide.", "example": "Surgery" }, "resources": { "type": "array", "description": "Resources allocated to this guide. Each item includes the resource ID, UID, display name, and type (`user` for staff, `facility` for rooms and equipment).\n", "items": { "$ref": "#/components/schemas/ResourceItem" } }, "recurrence": { "nullable": true, "description": "Recurrence metadata for this guide. `null` for one-time guides. `repeat_interval` is always a multiple of 604800 (1 week). `repeat_end_at` is `null` when the series repeats indefinitely.\n", "allOf": [ { "$ref": "#/components/schemas/AppointmentRecurrence" } ] } } }, "ResourceItem": { "type": "object", "description": "A resource (staff member or facility) allocated to an appointment or planning guide.", "properties": { "id": { "type": "integer", "description": "Numeric resource ID.", "example": 1932 }, "uid": { "type": "string", "description": "Globally unique string identifier for the resource.", "example": "resource_dC7T87I3VNJbcttDAeeID" }, "name": { "type": "string", "description": "Display name of the resource.", "example": "Dr Smith" }, "type": { "type": "string", "description": "Resource type. Either `user` (staff) or `facility` (rooms, equipment).", "enum": [ "user", "facility" ], "example": "user" } } }, "ResourceReference": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "pattern": "^resource_[a-zA-Z0-9]{21}$", "description": "Unique identifier for the resource", "example": "resource_ZzSHy5VDi3TNAlnXMUESj" }, "type": { "type": "string", "enum": [ "resource" ], "example": "resource" } } }, "SiteReference": { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "string", "pattern": "^site_[a-zA-Z0-9]{21}$", "description": "Unique identifier for the site", "example": "site_LSFNOSJExLMh0o7iZ55CH" }, "type": { "type": "string", "enum": [ "site" ], "example": "site" } } }, "Slot": { "type": "object", "required": [ "start", "duration", "available", "relationships" ], "properties": { "start": { "type": "string", "format": "time", "description": "Start time of the slot in ISO 8601 format with timezone offset", "example": "09:00:00.000+13:00" }, "duration": { "type": "integer", "description": "Duration of the slot in minutes", "minimum": 10, "maximum": 360, "example": 30 }, "available": { "type": "boolean", "description": "Whether this slot is available for booking", "example": true }, "relationships": { "$ref": "#/components/schemas/SlotRelationships" } } }, "SlotRelationships": { "type": "object", "required": [ "appointmentType" ], "properties": { "appointmentType": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "description": "Appointment types that are valid for this slot", "items": { "$ref": "#/components/schemas/AppointmentTypeReference" } } } } } } } }, "paths": { "/v1/appointment": { "get": { "summary": "Fetch an Appointment list", "description": "Gets a list of appointments.\n\nIt's recommended to use the GET/v2/appointment endpoint.", "operationId": "get-appointment", "tags": [ "Appointment" ], "security": [ { "bearerAuth": [ "read-appointment" ] } ], "parameters": [ { "name": "id", "in": "query", "description": "The ID number used by the system to uniquely identify an Appointment.", "schema": { "type": "string" } }, { "name": "recurrence_number", "in": "query", "description": "The number of the recurring appointment (if the appointment is recurring). E.g. 0 is the original, 1 is the first recurring appointment.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "If true, the Appointment is active and usable in ezyVet.", "schema": { "type": "boolean" } }, { "name": "created_at", "in": "query", "description": "The epoch time when the Appointment was created.", "schema": { "type": "string" } }, { "name": "modified_at", "in": "query", "description": "The epoch time when the Appointment was last modified.", "schema": { "type": "string" } }, { "name": "recurrence_interval", "in": "query", "description": "The interval between recurring appointments (in weeks).", "schema": { "type": "string", "default": 0 } }, { "name": "recurrence_end_time", "in": "query", "description": "The epoch time for when the recurrence ends (if the appointment is recurring).", "schema": { "type": "string" } }, { "name": "start_time", "in": "query", "description": "The epoch time for when the Appointment starts.", "schema": { "type": "string" } }, { "name": "duration", "in": "query", "description": "The duration of the Appointment in seconds.", "schema": { "type": "string" } }, { "name": "appointment_type_id", "in": "query", "description": "Refers to the ID of the AppointmentType of the Appointment.", "schema": { "type": "string" } }, { "name": "appointment_status_id", "in": "query", "description": "Refers to the ID of the AppointmentStatus of the Appointment.", "schema": { "type": "string" } }, { "name": "animal_id", "in": "query", "description": "Refers to the ID of the Animal.", "schema": { "type": "string" } }, { "name": "consult_id", "in": "query", "description": "Refers to the ID of the Consult.", "schema": { "type": "string" } }, { "name": "contact_id", "in": "query", "description": "Refers to the ID of the Contact.", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Limits the number of results returned.", "schema": { "type": "string", "default": 10 } }, { "name": "page", "in": "query", "description": "Specifies the page number of the result.", "schema": { "type": "string", "default": 1 } } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "appointment": { "type": "object", "properties": { "id": { "type": "string" }, "recurrence_number": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "recurrence_interval": { "type": "string" }, "recurrence_end_time": { "type": "string" }, "start_time": { "type": "string" }, "duration": { "type": "string" }, "details": { "type": "object", "properties": { "appointment_type_id": { "type": "string" }, "appointment_status_id": { "type": "string" }, "description": { "type": "string" }, "animal_id": { "type": "string" }, "consult_id": { "type": "string" }, "contact_id": { "type": "string" }, "resource_list": { "type": "array", "items": { "type": "string" } } } } } } } } }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v1/appointmentstatus": { "get": { "summary": "Fetch a Appointment Status list", "operationId": "get-appointmentstatus", "tags": [ "Appointment Status" ], "description": "Fetches a list containing [`AppointmentStatus`](#appointmentstatus)(s). (up to 10)", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "The ID number used by the system to uniquely identify a [`AppointmentStatus`](#appointmentstatus)." }, { "name": "active", "in": "query", "schema": { "type": "string" }, "description": "If **true**, the [`AppointmentStatus`](#appointmentstatus) is active and usable in ezyVet." }, { "name": "created_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`AppointmentStatus`](#appointmentstatus) was created." }, { "name": "modified_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`AppointmentStatus`](#appointmentstatus) was last modified." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "The name of the [`AppointmentStatus`](#appointmentstatus)." }, { "name": "limit", "in": "query", "schema": { "type": "string", "default": 10 }, "description": "Limits the number of items returned." }, { "name": "page", "in": "query", "schema": { "type": "string", "default": 1 }, "description": "Specifies the page number of the result." } ], "responses": { "200": { "description": "A list of appointment statuses", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "appointmentstatus": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" } } } } } }, "messages": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-appointmentstatus" ] } ] } }, "/v1/appointmenttype": { "get": { "summary": "Fetch an AppointmentType list", "operationId": "get-appointmenttype", "tags": [ "Appointment Type" ], "description": "Fetches a list containing [`AppointmentType`](#appointmenttype)(s). (up to 10)", "parameters": [ { "name": "id", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "The ID number used by the system to uniquely identify an [`AppointmentType`](#appointmenttype)." }, { "name": "active", "in": "query", "schema": { "type": "boolean" }, "description": "If **true**, the [`AppointmentType`](#appointmenttype) is active and usable in ezyVet." }, { "name": "created_at", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "The epoch time when the [`AppointmentType`](#appointmenttype) was created." }, { "name": "modified_at", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ] }, "description": "The epoch time when the [`AppointmentType`](#appointmenttype) was last modified." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "The name of the [`AppointmentType`](#appointmenttype)." }, { "name": "default_duration", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "default": 30 }, "description": "The default duration of the [`Appointment`](#appointment) **(in minutes)**." }, { "name": "limit", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "default": 10 }, "description": "Limits the number of results returned." }, { "name": "page", "in": "query", "schema": { "oneOf": [ { "type": "number" }, { "type": "string" } ], "default": 1 }, "description": "Specifies the page number of the result." } ], "responses": { "200": { "description": "A list of AppointmentTypes", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "appointmenttype": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" }, "default_duration": { "type": "string" } } } } } }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-appointmenttype" ] } ] } }, "/v1/resource": { "get": { "summary": "Fetch a Resource list", "operationId": "get-resource", "tags": [ "Resource" ], "description": "Fetches a list containing `Resource`(s).\nIt's recommended to use the [`v2/resource`](/#get-resourcev2) endpoint.", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "The ID number used by the system to uniquely identify a `Resource`." }, { "name": "active", "in": "query", "schema": { "type": "string" }, "description": "If **true**, the `Resource` is active and usable in ezyVet." }, { "name": "created_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the `Resource` was created." }, { "name": "modified_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the `Resource` was last modified." }, { "name": "ownership_id", "in": "query", "schema": { "type": "string" }, "description": "The ID of the `Ownership Separation` to which the `Resource` belongs." }, { "name": "name", "in": "query", "schema": { "type": "string" }, "description": "The name of the `Resource`." }, { "name": "type", "in": "query", "schema": { "type": "string" }, "description": "The type of the `Resource`: 'user' (default), 'facility'" }, { "name": "access", "in": "query", "schema": { "type": "string", "enum": [ "None", "On Calendar", "Member" ] }, "description": "The level of the access the `Resource` has." } ], "responses": { "200": { "description": "A list of resources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "object", "properties": { "id": { "type": "string" }, "active": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "name": { "type": "string" }, "type": { "type": "string" }, "access": { "type": "string" }, "ownership_id": { "type": "string" } } } } } }, "messages": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-resource" ] } ] } }, "/v2/appointment": { "post": { "summary": "Creates a single Appointment", "operationId": "create-appointmentv2", "tags": [ "Appointment V2" ], "description": "Creates a single [`Appointment`](#appointment).", "security": [ { "bearerAuth": [ "write-appointment" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "start_at": { "type": "string" }, "duration": { "type": "string" }, "type_id": { "type": "string" }, "status_id": { "type": "string" }, "description": { "type": "string", "nullable": true }, "animal_id": { "type": "string" }, "consult_id": { "type": "string", "nullable": true }, "contact_id": { "type": "string", "nullable": true }, "sales_resource": { "type": "number" }, "resources": { "type": "array", "items": { "type": "number" } } }, "required": [ "start_at", "duration", "type_id", "status_id", "sales_resource", "resources" ] } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "transaction_id": { "type": "string" }, "timestamp": { "type": "number" } }, "required": [ "transaction_id", "timestamp" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "appointment": { "type": "object", "properties": { "id": { "type": "string" }, "created_at": { "type": "string" }, "modified_at": { "type": "string" }, "active": { "type": "boolean" }, "start_at": { "type": "string" }, "duration": { "type": "string" }, "type_id": { "type": "string" }, "status_id": { "type": "string" }, "description": { "type": "string", "nullable": true }, "animal_id": { "type": "string" }, "consult_id": { "type": "string", "nullable": true }, "contact_id": { "type": "string", "nullable": true }, "sales_resource": { "type": "number" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" } }, "required": [ "id" ] } } }, "required": [ "id", "created_at", "modified_at", "active", "start_at", "duration", "type_id", "status_id", "sales_resource", "resources" ] } } }, "required": [ "appointment" ] }, "messages": { "type": "array", "items": { "type": "string" } } }, "required": [ "meta", "items", "messages" ] } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } }, "get": { "summary": "Fetch an Appointment list (V2)", "operationId": "get-appointmentv2", "security": [ { "bearerAuth": [ "read-appointment" ] } ], "tags": [ "Appointment V2" ], "description": "Fetch a list of [`Appointment`](#appointment-v2)(s). (up to 200)", "parameters": [ { "name": "id", "in": "query", "schema": { "type": "string" }, "description": "The ID number used by the system to uniquely identify an [`Appointment`](#appointment-v2)." }, { "name": "created_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`Appointment`](#appointment-v2) was created." }, { "name": "modified_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time when the [`Appointment`](#appointment-v2) was last modified." }, { "name": "active", "in": "query", "schema": { "type": "boolean" }, "description": "If **true**, the [`Appointment`](#appointment-v2) is active and usable in ezyVet." }, { "name": "start_at", "in": "query", "schema": { "type": "string" }, "description": "The epoch time for when the [`Appointment`](#appointment-v2) starts." }, { "name": "duration", "in": "query", "schema": { "type": "string" }, "description": "The duration of the [`Appointment`](#appointment-v2) in seconds." }, { "name": "type_id", "in": "query", "schema": { "type": "string" }, "description": "Refers to the ID of the [`AppointmentType`](#appointmenttype) of the [`Appointment`](#appointment-v2)." }, { "name": "status_id", "in": "query", "schema": { "type": "string" }, "description": "Refers to the ID of the [`AppointmentStatus`](#appointmentstatus) of the [`Appointment`](#appointment-v2)." }, { "name": "animal_id", "in": "query", "schema": { "type": "string" }, "description": "Refers to the ID of the [`Animal`](#animal)." }, { "name": "consult_id", "in": "query", "schema": { "type": "string" }, "description": "Refers to the ID of the [`Consult`](#consult)." }, { "name": "contact_id", "in": "query", "schema": { "type": "string" }, "description": "Refers to the ID of the [`Contact`](#contact)." }, { "name": "sales_resource", "in": "query", "schema": { "type": "number" }, "description": "ID of the [`SalesResource`](#resource) allocated to the [`Appointment`](#appointment-v2)." } ], "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "items_page": { "type": "number" }, "items_page_total": { "type": "number" }, "items_page_size": { "type": "number" }, "items_total": { "type": "number" }, "transaction_id": { "type": "string" }, "timestamp": { "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "appointment": { "type": "object", "properties": { "id": { "type": "number" }, "uid": { "type": "string" }, "created_at": { "type": "number" }, "modified_at": { "type": "number" }, "active": { "type": "boolean" }, "start_at": { "type": "number" }, "duration": { "type": "number" }, "type_id": { "type": "number" }, "type_uid": { "type": "string" }, "status_id": { "type": "number" }, "description": { "type": "string" }, "animal_id": { "type": "number", "nullable": true }, "animal_uid": { "type": "string", "nullable": true }, "consult_id": { "type": "string", "nullable": true }, "contact_id": { "type": "number", "nullable": true }, "contact_uid": { "type": "string", "nullable": true }, "sales_resource": { "type": "number" }, "event_group": { "type": "number" }, "destination_address": { "type": "number" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" } } } }, "cancellation_reason": { "type": "number", "nullable": true }, "cancellation_reason_text": { "type": "string", "nullable": true } } } } } }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/appointment/{id}": { "patch": { "summary": "Updates an existing Appointment", "operationId": "update-appointmentv2", "tags": [ "Appointment V2" ], "description": "Updates an existing [`Appointment`](#appointment-v2).\n\nAll body fields are optional; only the fields you include are changed.\n\n**Cancelling an appointment:** send `cancel: true` together with a cancellation reason — either `cancellation_reason` (the ID of a cancellation reason record) or `cancellation_reason_text` (a free-text reason). The two are mutually exclusive; if both are supplied, `cancellation_reason` takes precedence. When `cancel: true` is sent, only the cancellation details are updated — any other fields in the same request are ignored.\n\n**Updating other fields:** to change appointment details such as `status_id`, `description`, `animal_id` or `consult_id`, send the request without `cancel: true`.", "parameters": [ { "name": "id", "in": "path", "description": "The ID of the appointment to update.", "required": true, "schema": { "type": "number" } } ], "requestBody": { "content": { "application/merge-patch+json": { "schema": { "type": "object", "properties": { "cancel": { "type": "boolean", "description": "If true, the Appointment is cancelled. When cancelling, supply a cancellation reason via `cancellation_reason` or `cancellation_reason_text`. Other fields in the same request are ignored while cancelling." }, "cancellation_reason": { "type": "number", "description": "The ID of the cancellation reason record the Appointment is cancelled for. Used only when `cancel` is true. Mutually exclusive with `cancellation_reason_text`." }, "cancellation_reason_text": { "type": "string", "description": "A free-text reason for the appointment being cancelled. Used only when `cancel` is true, and persisted when sent alongside `cancel: true`. Mutually exclusive with `cancellation_reason`." }, "status_id": { "type": "string", "description": "Refers to the ID of the AppointmentStatus of the Appointment. Applied when the request is not a cancellation." }, "description": { "type": "string", "description": "The Appointment description. This serves as the reason for appointment. Applied when the request is not a cancellation." }, "animal_id": { "type": "string", "description": "Refers to the ID of the Animal. Applied when the request is not a cancellation." }, "consult_id": { "type": "string", "description": "Refers to the ID of the Consult. Applied when the request is not a cancellation." } } } } } }, "responses": { "200": { "description": "Successful response", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "items_processed": { "type": "number" }, "transaction_id": { "type": "string" }, "timestamp": { "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "appointment": { "type": "object", "properties": { "id": { "type": "number" }, "uid": { "type": "string" }, "created_at": { "type": "number" }, "modified_at": { "type": "number" }, "active": { "type": "boolean" }, "start_at": { "type": "number" }, "duration": { "type": "number" }, "type_id": { "type": "number" }, "type_uid": { "type": "string" }, "status_id": { "type": "number" }, "description": { "type": "string" }, "animal_id": { "type": "number", "nullable": true }, "animal_uid": { "type": "string", "nullable": true }, "consult_id": { "type": "string", "nullable": true }, "contact_id": { "type": "number", "nullable": true }, "contact_uid": { "type": "string", "nullable": true }, "sales_resource": { "type": "number" }, "event_group": { "type": "number" }, "destination_address": { "type": "number" }, "resources": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "number" } } } }, "cancellation_reason": { "type": "number", "nullable": true }, "cancellation_reason_text": { "type": "string", "nullable": true } } } } } }, "messages": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "write-appointment" ] } ] } }, "/v2/appointmenttype": { "get": { "summary": "Fetches a list containing AppointmentTypes", "operationId": "get-appointmenttypev2", "tags": [ "Appointment Type V2" ], "parameters": [ { "name": "id", "in": "query", "description": "The ID number used by the system to uniquely identify an AppointmentType.", "schema": { "type": "number" } }, { "name": "uid", "in": "query", "description": "The ID number used by the system to uniquely identify an AppointmentType across all ezyVet sites.", "schema": { "type": "string" } }, { "name": "active", "in": "query", "description": "If true, the AppointmentType is active and usable in ezyVet.", "schema": { "type": "boolean" } }, { "name": "limit", "in": "query", "description": "Limits the number of results returned.", "schema": { "type": "number", "default": 10 } }, { "name": "page", "in": "query", "description": "Specifies the page number of the result.", "schema": { "type": "number", "default": 1 } } ], "responses": { "200": { "description": "A list of AppointmentType(s)", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "items_page": { "type": "number" }, "items_page_total": { "type": "number" }, "items_page_size": { "type": "number" }, "items_total": { "type": "number" }, "transaction_id": { "type": "string" }, "timestamp": { "type": "number" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "appointmenttype": { "type": "object", "properties": { "id": { "type": "number" }, "uid": { "type": "string" }, "active": { "type": "boolean" }, "name": { "type": "string" }, "default_duration": { "type": "number", "default": 30 } } } } } }, "messages": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-appointmenttype" ] } ] } }, "/v2/resource": { "get": { "summary": "Fetches a list of Resources", "operationId": "get-resourcev2", "description": "Fetches a list containing `Resource`(s).", "tags": [ "Resource V2" ], "parameters": [ { "name": "id", "in": "query", "description": "The ID number used by the system to uniquely identify an Resource.", "schema": { "type": "number" } }, { "name": "uid", "in": "query", "description": "The ID number used by the system to uniquely identify an Resource across all ezyVet sites.", "schema": { "type": "string" } }, { "name": "created_at", "in": "query", "description": "The epoch time when the Resource was created.", "schema": { "type": "number" } }, { "name": "modified_at", "in": "query", "description": "The epoch time when the Resource was last modified.", "schema": { "type": "number" } }, { "name": "active", "in": "query", "description": "If true, the Resource is active and usable in ezyVet.", "schema": { "type": "boolean" } }, { "name": "associated_type", "in": "query", "description": "The type of the Resource: 'user', 'facility'.", "schema": { "type": "string" } }, { "name": "associated_id", "in": "query", "description": "The ID number used by the system to uniquely identify a user.", "schema": { "type": "number" } }, { "name": "associated_uid", "in": "query", "description": "The ID number used by the system to uniquely identify a user across all ezyVet sites.", "schema": { "type": "string" } }, { "name": "access", "in": "query", "description": "The level of the access the Resource has. The value can be one of the following: 'None', 'On Calendar' or 'Member'.", "schema": { "type": "string", "enum": [ "None", "On Calendar", "Member" ] } }, { "name": "ownership_uid", "in": "query", "description": "The ID of the Ownership Separation to which this Resource belongs across all ezyVet sites.", "schema": { "type": "string" } }, { "name": "ownership_id", "in": "query", "description": "The ID of the Ownership Separation to which this Resource belongs.", "schema": { "type": "number" } } ], "responses": { "200": { "description": "A list of Resources.", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "resource": { "type": "object", "properties": { "id": { "type": "number" }, "uid": { "type": "string" }, "created_at": { "type": "number" }, "modified_at": { "type": "number" }, "active": { "type": "boolean" }, "name": { "type": "string" }, "associated_type": { "type": "string" }, "associated_id": { "type": "number" }, "associated_uid": { "type": "string" }, "access": { "type": "string" }, "ownership_uid": { "type": "string" }, "ownership_id": { "type": "number" } } } } } }, "messages": { "type": "array", "items": { "type": "object" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } }, "security": [ { "bearerAuth": [ "read-resource" ] } ] } }, "/ezycab/availability": { "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyCAB Production Environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyCAB Trial Environment" } ], "get": { "security": [ { "bearerAuth": [ "read-appointment" ] } ], "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyVet production environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyVet trial environment" } ], "deprecated": true, "operationId": "get-availability", "tags": [ "Availability" ], "summary": "Get bookable appointment slots (Deprecated)", "description": "> **Deprecated.** Use [`/v4/calendar/availability`](/#get-calendar-availability) instead. This endpoint is scheduled to be sunset on **20 January 2027** — migrate before then to avoid service disruption. See the [deprecation notice](/deprecated.html#deprecation-notice) for the full schedule. Responses include `Deprecated` and `Sunset` headers.\n\nGets bookable appointment slots | Rate limit : 300 calls/minute", "parameters": [ { "name": "resources[]", "in": "query", "description": "- The UID(s) of the resource(s) to return availability for. \n - This parameter can be added multiple times to request more than one resource. \n - A minimum of 1 and a maximum of 5 resources may be requested per call. \n - Each resource UID must be unique.", "example": "resource_Tr4l0W5LbTs7aTGSuzi5n", "required": true, "schema": { "type": "string" } }, { "name": "dates[]", "in": "query", "description": "- The date(s) to return availability for, in ISO 8601 format (YYYY-MM-DD). \n - This parameter can be added multiple times to request more than one date. \n - A minimum of 1 and a maximum of 7 dates may be requested per call. \n - Each date must be unique. \n - A date must not be in the past and must be no more than 6 months in the future.", "example": "2024-06-09", "required": true, "schema": { "type": "string" } }, { "name": "duration", "in": "query", "description": "- The duration of the appointment slots (in minutes). \n - Default minimum value is 10 but can be reduced to 5 with additional filtering (See Availability guide). \n - Maximum value is 360. \n - Increments in 5 minutes.\n\nRefer to the availability guide for more information.", "example": 15, "required": true, "schema": { "type": "number" } }, { "name": "filter[slots.available][eq]", "in": "query", "description": "Filtering by whether the appointment slots are available or not.", "example": true, "required": false, "schema": { "type": "boolean" } }, { "name": "filter[slots.appointmentType.id][in]", "in": "query", "description": "- Filtering by appointment type using the UID. \n - Can provide multiple UIDs separated by commas. \n - Required when duration is set to 5 minutes (a 5-minute duration is only permitted alongside an appointment type filter).", "example": "appointmentType_0C0qtekyEL2A0XDUUSbDz", "schema": { "type": "string" } } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Availability" } } } }, "400": { "description": "Bad Request", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "number", "example": 400 }, "message": { "type": "string", "example": "Validation failed" }, "errors": { "type": "array", "items": { "type": "object", "properties": { "code": { "type": "string", "example": "invalid_string" }, "message": { "type": "string", "example": "Duration must be a numeric string" }, "path": { "type": "array", "items": { "type": "string", "example": "duration" } } } } } } }, "examples": { "validationError": { "summary": "Invalid query parameter (schema validation)", "value": { "statusCode": 400, "message": "Validation failed", "errors": [ { "code": "too_big", "message": "Maximum 5 resources allowed", "path": [ "resources" ] } ] } }, "dateOutOfRange": { "summary": "A date is in the past or more than 6 months in the future", "value": { "statusCode": 400, "message": "Date cannot be more than 6 months in the future (date: 2025-12-25)" } }, "durationBelowMinimum": { "summary": "Duration below the allowed minimum (5 min requires an appointment type filter)", "value": { "statusCode": 400, "message": "A planning guide is required to use a 5 min duration" } } } } } }, "401": { "description": "Unauthorized - Missing, invalid, or expired access token.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 401 }, "message": { "type": "string", "example": "Token Invalid" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions, missing required scope (read-appointment), or the ezyCAB service is not enabled for this site.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Invalid Scope" } } } } } }, "404": { "description": "Not Found - A requested resource does not exist for this site.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 404 }, "message": { "type": "string", "example": "Resource is not found" } } } } } }, "429": { "description": "Too Many Requests - The per-site rate limit has been exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 429 }, "message": { "type": "string", "example": "Too Many Requests" } } } } } }, "500": { "description": "Internal Server Error - An unexpected error occurred while processing the request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 500 }, "message": { "type": "string", "example": "Internal server error" } } } } } } } } }, "/v4/calendar/booking": { "post": { "summary": "Create a new appointment booking", "description": "Creates an appointment with associated consultation and billing triggers in the ezyVet system.", "operationId": "create-booking", "tags": [ "Appointment Booking" ], "security": [ { "bearerAuth": [ "create-booking" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" } } } }, "responses": { "200": { "description": "Successful booking creation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ezycab/booking": { "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyCAB Production Environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyCAB Trial Environment" } ], "post": { "summary": "Create a new appointment booking", "description": "Its recommended to use the [`v4/calendar/booking` endpoint](#create-booking). This endpoint is deprecated and scheduled to be sunset on **28 March 2027** — see the [deprecation notice](/deprecated). Responses include `Deprecated` and `Sunset` headers.\n\nCreates an appointment with associated consultation and billing triggers in the ezyVet system.", "operationId": "create-booking-deprecated", "deprecated": true, "tags": [ "Appointment Booking" ], "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyVet production environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyVet trial environment" } ], "security": [ { "bearerAuth": [ "create-booking" ] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingRequest" } } } }, "responses": { "200": { "description": "Successful booking creation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BookingResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2/shelteranimalbooking/{id}": { "get": { "summary": "Fetch a Specific Shelter Animal Booking", "operationId": "get-shelteranimalbooking", "tags": [ "Shelter Animal Booking" ], "description": "Fetches a specific Shelter Animal Booking specified by its `id`.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "number" }, "description": "The ID number used by the system to uniquely identify a Shelter Animal Booking." } ], "security": [ { "bearerAuth": [ "read-shelteranimalbooking" ] } ], "responses": { "200": { "description": "A single shelter animal booking", "content": { "application/json": { "schema": { "type": "object", "properties": { "meta": { "type": "object", "properties": { "timestamp": { "type": "string" }, "items_page": { "type": "string" }, "items_page_total": { "type": "string" }, "items_page_size": { "type": "string" }, "items_total": { "type": "string" } } }, "items": { "type": "array", "items": { "type": "object", "properties": { "shelteranimalbooking": { "type": "object", "properties": { "id": { "type": "number" }, "created_at": { "type": "number" }, "modified_at": { "type": "number" }, "active": { "type": "boolean" }, "animal_id": { "type": "number" }, "start_time": { "type": "number" }, "end_time": { "type": "number" }, "consult_id": { "type": "number", "nullable": true }, "status": { "type": "string" }, "shelter_resource_place_id": { "type": "number" }, "contact_id": { "type": "number" }, "shelter_resource_id": { "type": "number" }, "shelter_resource_name": { "type": "string" }, "shelter_resource_ownership_id": { "type": "number" }, "comment": { "type": "string" } } } } } }, "messages": { "type": "array", "items": {} } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ezycab/v2.1/appointments": { "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyCAB Production Environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyCAB Trial Environment" } ], "get": { "deprecated": true, "summary": "Fetch an appointment list (V2.1) (Deprecated)", "operationId": "get-appointmentsv21", "tags": [ "Appointment V2" ], "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyVet production environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyVet trial environment" } ], "description": "> **Deprecated.** Use [`/v2.1/calendar/appointments`](/#get-calendar-appointmentsv21) instead. This endpoint is scheduled to be sunset on **20 January 2027** — migrate before then to avoid service disruption. See the [deprecation notice](/deprecated.html#deprecation-notice) for the full schedule. Responses include `Deprecated` and `Sunset` headers.\n\nFetches a list of appointments. Recurring appointments include a `recurrence` object; one-time appointments have `recurrence: null`.\n\nThis endpoint is designed for integrations that maintain a local copy of appointments for booking availability and calendar purposes.\n\n## Recommended sync pattern\n\n1. **Initial backfill**: Bound your historical window with `filter[start_at][gte]` and `filter[start_at][lte]` (e.g. last 30 days to next 90 days). Omit `filter[active][eq]` so you receive both active and cancelled appointments in a single pass.\n2. **Incremental polling**: Use `filter[modified_at][gte]` with the highest `modified_at` from your last response. This returns only records that changed since your last poll, including cancellations (`active: false`) so you can remove them from your local copy.\n\n## Pagination\n\nPass `meta.nextToken` from the previous response as the `nextToken` query parameter to fetch the next page. When `nextToken` is absent or null there are no more pages.\n\n## Authentication\n\nRequires the `read-appointment` JWT scope.", "security": [ { "bearerAuth": [ "read-appointment" ] } ], "parameters": [ { "name": "filter[id][in]", "in": "query", "description": "Comma-separated list of appointment IDs. Use for targeted batch re-fetches when a client detects inconsistency and needs to refresh specific records.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "12345", "12346" ] }, { "name": "filter[modified_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only appointments modified at or after this timestamp. Use as the anchor for incremental polling — store the highest `modified_at` from your last response and pass it on the next request. Because this is inclusive, deduplicate returned records by `id` to avoid reprocessing the boundary record.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-15T08:30:00Z" }, { "name": "filter[start_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only appointments starting at or after this time. Combine with `filter[start_at][lte]` to define a calendar window for backfill.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "filter[start_at][lte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only appointments starting at or before this time.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-04-01T00:00:00Z" }, { "name": "filter[active][eq]", "in": "query", "description": "Filter by active status.\n- `true`: active appointments only\n- `false`: inactive/cancelled appointments only\n- Omitted: all appointments regardless of status\n\nFor sync integrations, omit this filter so cancelled appointments (`active: false`) are included and can be removed from your local copy.", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "filter[resources.uid][in]", "in": "query", "description": "Comma-separated list of resource UIDs. Returns appointments assigned to any of the specified resources (vets, nurses, rooms, etc.).", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "resource_cZ9Qx1JMVkLAXsxlGYxVM", "resource_mkuy7NxCv86hzUWmG8Qcd" ] }, { "name": "pageSize", "in": "query", "description": "Number of appointments to return per page. Defaults to 1000, maximum 5000.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 }, "example": 1000 }, { "name": "nextToken", "in": "query", "description": "Pagination cursor returned in `meta.nextToken` from a previous response. Omit on the first request.", "required": false, "schema": { "type": "string" }, "example": "AB3e7Z2i9FJu0j7hLExLp" } ], "responses": { "200": { "description": "Successful response with appointment list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAppointmentsV21Response" }, "examples": { "withRecurrence": { "summary": "Page with a recurring and a one-time appointment", "value": { "meta": { "nextToken": "AB3e7Z2i9FJu0j7hLExLp" }, "data": [ { "id": 12345, "uid": "appointment_X8CLo8J3gEBtRbykwia6q", "created_at": 1307498299, "modified_at": 1765395429, "active": true, "start_at": 1307491200, "duration": 2400, "type_id": 3, "type_uid": "appointmentType_jemy7oGJjj0BExij6D3xk", "status_id": 1, "status_uid": "appointmentStatus_1N3r94lmYh5okkql6jeGF", "description": "Annual checkup", "animal_id": 9, "animal_uid": "animal_HeXPdBCykd60T8NrhKPoj", "consult_id": null, "consult_uid": null, "contact_id": 14, "contact_uid": "contact_ATplEuzOYEWqmfQ95sMZJ", "sales_resource": 1932, "sales_resource_uid": "resource_dC7T87I3VNJbcttDAeeID", "event_group": 36, "destination_address": 0, "resources": [ { "id": 1932, "uid": "resource_dC7T87I3VNJbcttDAeeID", "name": "Dr Smith", "type": "user" } ], "cancellation_reason": null, "cancellation_reason_text": null, "recurrence": { "repeat_interval": 604800, "repeat_end_at": 1798761600 } }, { "id": 12346, "uid": "appointment_Y9DMp9K4hFCuSczkxjb7r", "created_at": 1307498300, "modified_at": 1765395430, "active": true, "start_at": 1307577600, "duration": 1800, "type_id": 3, "type_uid": "appointmentType_jemy7oGJjj0BExij6D3xk", "status_id": 1, "status_uid": "appointmentStatus_1N3r94lmYh5okkql6jeGF", "description": "One-time appointment", "animal_id": 10, "animal_uid": "animal_ZaYQeCDzlj71U9sohLQpk", "consult_id": 6863, "consult_uid": "consult_jPdsIZXQaGxoLGnVy5CXi", "contact_id": 15, "contact_uid": "contact_BUqmFvzPZFXrnhR06tNAK", "sales_resource": 1933, "sales_resource_uid": "resource_SsCmMVgUkJP8nmkewibxl", "event_group": null, "destination_address": 0, "resources": [ { "id": 1933, "uid": "resource_SsCmMVgUkJP8nmkewibxl", "name": "Dr Jones", "type": "user" } ], "cancellation_reason": null, "cancellation_reason_text": null, "recurrence": null } ] } }, "lastPage": { "summary": "Last page — no nextToken, includes a cancelled appointment", "value": { "meta": {}, "data": [ { "id": 12347, "uid": "appointment_Z0ENq0L5iGDvTdAlykc8s", "created_at": 1307498301, "modified_at": 1765395431, "active": false, "start_at": 1307664000, "duration": 900, "type_id": 1, "type_uid": "appointmentType_kfnz8pHKkt1CFpjk7E4yl", "status_id": 5, "status_uid": "appointmentStatus_5P6s05onZi8pllrm7khHI", "description": "", "animal_id": 11, "animal_uid": "animal_AbZRfEDamk82V0tpiMRql", "consult_id": null, "consult_uid": null, "contact_id": 16, "contact_uid": "contact_CVrnGwAQAGYsoiS17uOBL", "sales_resource": 1934, "sales_resource_uid": "resource_eEtNhQFLlu2GDwpnZffJE", "event_group": null, "destination_address": 0, "resources": [], "cancellation_reason": "client_request", "cancellation_reason_text": "Client called to cancel", "recurrence": null } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions or missing required scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Insufficient permissions. Required scope: read-appointment" }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/ezycab/v2.1/planning-guides": { "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyCAB Production Environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyCAB Trial Environment" } ], "get": { "deprecated": true, "summary": "Fetch a planning guide list (V2.1) (Deprecated)", "operationId": "get-planningguidesv21", "tags": [ "Planning Guides" ], "servers": [ { "url": "https://apiv2.ezyvet.com", "description": "ezyVet production environment" }, { "url": "https://apiv2.trial.ezyvet.com", "description": "ezyVet trial environment" } ], "description": "> **Deprecated.** Use [`/v2.1/calendar/planning-guides`](/#get-calendar-planningguidesv21) instead. This endpoint is scheduled to be sunset on **20 January 2027** — migrate before then to avoid service disruption. See the [deprecation notice](/deprecated.html#deprecation-notice) for the full schedule. Responses include `Deprecated` and `Sunset` headers.\n\nFetches a list of planning guides (scheduling blocks that define when a resource is available for bookings). Planning guides have `appointmentdata_calendartype = 'Guide'`.\n\nThis endpoint is designed for integrations that maintain a local copy of planning guide availability windows.\n\n## Recommended sync pattern\n\n1. **Initial backfill**: Record the current UTC timestamp before you start. Bound your window with `filter[start_at][gte]` and `filter[start_at][lte]`. Omit `filter[active][eq]` to receive both active and inactive guides in a single pass.\n2. **Incremental polling**: Use `filter[modified_at][gte]` with the timestamp recorded at the start of the backfill (not the highest `modified_at` seen in responses). This ensures records modified mid-backfill are not missed. Advance the cursor to the previous poll's start time on each subsequent poll.\n\n## Pagination\n\nPass `meta.nextToken` from the previous response as the `nextToken` query parameter to fetch the next page. When `nextToken` is absent or null there are no more pages.\n\n## Authentication\n\nRequires the `read-appointment` JWT scope.", "security": [ { "bearerAuth": [ "read-appointment" ] } ], "parameters": [ { "name": "filter[id][in]", "in": "query", "description": "Comma-separated list of planning guide IDs. Use for targeted batch re-fetches.", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "2048", "2049" ] }, { "name": "filter[modified_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only guides modified at or after this timestamp. Use as the anchor for incremental polling.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-15T08:30:00Z" }, { "name": "filter[start_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only guides starting at or after this time. Combine with `filter[start_at][lte]` to define a calendar window for backfill.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-01-01T00:00:00Z" }, { "name": "filter[start_at][lte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only guides starting at or before this time.", "required": false, "schema": { "type": "string", "format": "date-time" }, "example": "2026-04-01T00:00:00Z" }, { "name": "filter[active][eq]", "in": "query", "description": "Filter by active status.\n- `true`: active guides only\n- `false`: inactive guides only\n- Omitted: all guides regardless of status", "required": false, "schema": { "type": "boolean" }, "example": true }, { "name": "filter[resources.uid][in]", "in": "query", "description": "Comma-separated list of resource UIDs. Returns guides assigned to any of the specified resources (vets, nurses, rooms, etc.).", "required": false, "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } }, "example": [ "resource_iHmhFtUJBmDYB5m8rMTI0", "resource_hvy20slsY9M8886UigeIF" ] }, { "name": "pageSize", "in": "query", "description": "Number of guides to return per page. Defaults to 1000, maximum 5000.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 }, "example": 1000 }, { "name": "nextToken", "in": "query", "description": "Pagination cursor returned in `meta.nextToken` from a previous response. Omit on the first request.", "required": false, "schema": { "type": "string" }, "example": "AB3e7Z2i9FJu0j7hLExLp" } ], "responses": { "200": { "description": "Successful response with planning guide list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPlanningGuidesV21Response" }, "examples": { "withRecurrence": { "summary": "Page with a recurring and a one-time planning guide", "value": { "meta": { "nextToken": "AB3e7Z2i9FJu0j7hLExLp" }, "data": [ { "id": 2048, "uid": "appointment_uJMYy7DC3CT9MsPB0r3HU", "created_at": 1307498299, "modified_at": 1765395429, "active": true, "start_at": 1307491200, "duration": 28800, "type_id": 8, "type_uid": "appointmentType_jemy7oGJjj0BExij6D3xk", "description": "", "resources": [ { "id": 36, "uid": "resource_dC7T87I3VNJbcttDAeeID", "name": "Dr Smith", "type": "user" } ], "recurrence": { "repeat_interval": 604800, "repeat_end_at": null } }, { "id": 2049, "uid": "appointment_vKNZz8ED4DU0HtQC1s4IV", "created_at": 1307498300, "modified_at": 1765395430, "active": true, "start_at": 1307577600, "duration": 10800, "type_id": 7, "type_uid": "appointmentType_kfnz8pHKkt1CFpjk7E4yl", "description": "", "resources": [ { "id": 36, "uid": "resource_dC7T87I3VNJbcttDAeeID", "name": "Dr Smith", "type": "user" } ], "recurrence": null } ] } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Forbidden - Insufficient permissions or missing required scope", "content": { "application/json": { "schema": { "type": "object", "properties": { "statusCode": { "type": "integer", "example": 403 }, "message": { "type": "string", "example": "Insufficient permissions. Required scope: read-appointment" }, "error": { "type": "string", "example": "Forbidden" } } } } } }, "500": { "$ref": "#/components/responses/InternalError" } } } }, "/v2.1/calendar/appointments": { "get": { "tags": [ "Appointment V2" ], "summary": "Fetch an appointment list (V2.1)", "description": "Fetches a list of appointments. Recurring appointments include a `recurrence` object; one-time appointments have `recurrence: null`.\n\nThis endpoint is designed for integrations that maintain a local copy of appointments for booking availability and calendar purposes.\n\n## Recommended sync pattern\n\n1. **Initial backfill**: Bound your historical window with `filter[start_at][gte]` and `filter[start_at][lte]` (e.g. last 30 days to next 90 days). Omit `filter[active][eq]` so you receive both active and cancelled appointments in a single pass.\n2. **Incremental polling**: Use `filter[modified_at][gte]` with the highest `modified_at` from your last response. This returns only records that changed since your last poll, including cancellations (`active: false`) so you can remove them from your local copy.\n\n## Pagination\n\nPass `meta.nextToken` from the previous response as the `nextToken` query parameter to fetch the next page. When `nextToken` is absent or null there are no more pages.\n\n## Authentication\n\nRequires the `read-appointment` JWT scope.\n", "operationId": "get-calendar-appointmentsv21", "security": [ { "bearerAuth": [ "read-appointment" ] } ], "parameters": [ { "name": "filter[id][in]", "in": "query", "description": "Comma-separated list of appointment IDs. Use for targeted batch re-fetches when a client detects inconsistency and needs to refresh specific records.\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "examples": { "Example": { "summary": "", "value": [ "12345", "12346" ] } } }, { "name": "filter[modified_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only appointments modified at or after this timestamp. Use as the anchor for incremental polling — store the highest `modified_at` from your last response and pass it on the next request. Because this is inclusive, deduplicate returned records by `id` to avoid reprocessing the boundary record.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "examples": { "Example": { "summary": "", "value": "2026-01-15T08:30:00Z" } } }, { "name": "filter[start_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only appointments starting at or after this time. Combine with `filter[start_at][lte]` to define a calendar window for backfill.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "examples": { "Example": { "summary": "", "value": "2026-01-01T00:00:00Z" } } }, { "name": "filter[start_at][lte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only appointments starting at or before this time.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "examples": { "Example": { "summary": "", "value": "2026-04-01T00:00:00Z" } } }, { "name": "filter[active][eq]", "in": "query", "description": "Filter by active status.\n- `true`: active appointments only\n- `false`: inactive/cancelled appointments only\n- Omitted: all appointments regardless of status\n\nFor sync integrations, omit this filter so cancelled appointments (`active: false`) are included and can be removed from your local copy.\n", "required": false, "schema": { "type": "boolean" }, "examples": { "Example": { "summary": "", "value": true } } }, { "name": "filter[resources.uid][in]", "in": "query", "description": "Comma-separated list of resource UIDs. Returns appointments assigned to any of the specified resources (vets, nurses, rooms, etc.).\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "examples": { "Example": { "summary": "", "value": [ "resource_cZ9Qx1JMVkLAXsxlGYxVM", "resource_mkuy7NxCv86hzUWmG8Qcd" ] } } }, { "name": "pageSize", "in": "query", "description": "Number of appointments to return per page. Defaults to 1000, maximum 5000.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 }, "examples": { "Example": { "summary": "", "value": 1000 } } }, { "name": "nextToken", "in": "query", "description": "Pagination cursor returned in `meta.nextToken` from a previous response. Omit on the first request.\n", "required": false, "schema": { "type": "string" }, "examples": { "Example": { "summary": "", "value": "AB3e7Z2i9FJu0j7hLExLp" } } } ], "responses": { "200": { "description": "Successful response with appointment list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAppointmentsV21Response" }, "examples": { "withRecurrence": { "summary": "Page with a recurring and a one-time appointment", "value": { "meta": { "nextToken": "AB3e7Z2i9FJu0j7hLExLp" }, "data": [ { "id": 12345, "uid": "appointment_X8CLo8J3gEBtRbykwia6q", "created_at": 1307498299, "modified_at": 1765395429, "active": true, "start_at": 1307491200, "duration": 2400, "type_id": 3, "type_uid": "appointmentType_jemy7oGJjj0BExij6D3xk", "status_id": 1, "status_uid": "appointmentStatus_1N3r94lmYh5okkql6jeGF", "description": "Annual checkup", "animal_id": 9, "animal_uid": "animal_HeXPdBCykd60T8NrhKPoj", "consult_id": null, "consult_uid": null, "contact_id": 14, "contact_uid": "contact_ATplEuzOYEWqmfQ95sMZJ", "sales_resource": 1932, "sales_resource_uid": "resource_dC7T87I3VNJbcttDAeeID", "event_group": 36, "destination_address": 0, "resources": [ { "id": 1932, "uid": "resource_dC7T87I3VNJbcttDAeeID", "name": "Dr Smith", "type": "user" } ], "cancellation_reason": null, "cancellation_reason_text": null, "recurrence": { "repeat_interval": 604800, "repeat_end_at": 1798761600 } }, { "id": 12346, "uid": "appointment_Y9DMp9K4hFCuSczkxjb7r", "created_at": 1307498300, "modified_at": 1765395430, "active": true, "start_at": 1307577600, "duration": 1800, "type_id": 3, "type_uid": "appointmentType_jemy7oGJjj0BExij6D3xk", "status_id": 1, "status_uid": "appointmentStatus_1N3r94lmYh5okkql6jeGF", "description": "One-time appointment", "animal_id": 10, "animal_uid": "animal_ZaYQeCDzlj71U9sohLQpk", "consult_id": 6863, "consult_uid": "consult_jPdsIZXQaGxoLGnVy5CXi", "contact_id": 15, "contact_uid": "contact_BUqmFvzPZFXrnhR06tNAK", "sales_resource": 1933, "sales_resource_uid": "resource_SsCmMVgUkJP8nmkewibxl", "event_group": null, "destination_address": 0, "resources": [ { "id": 1933, "uid": "resource_SsCmMVgUkJP8nmkewibxl", "name": "Dr Jones", "type": "user" } ], "cancellation_reason": null, "cancellation_reason_text": null, "recurrence": null } ] } }, "lastPage": { "summary": "Last page — no nextToken, includes a cancelled appointment", "value": { "meta": {}, "data": [ { "id": 12347, "uid": "appointment_Z0ENq0L5iGDvTdAlykc8s", "created_at": 1307498301, "modified_at": 1765395431, "active": false, "start_at": 1307664000, "duration": 900, "type_id": 1, "type_uid": "appointmentType_kfnz8pHKkt1CFpjk7E4yl", "status_id": 5, "status_uid": "appointmentStatus_5P6s05onZi8pllrm7khHI", "description": "", "animal_id": 11, "animal_uid": "animal_AbZRfEDamk82V0tpiMRql", "consult_id": null, "consult_uid": null, "contact_id": 16, "contact_uid": "contact_CVrnGwAQAGYsoiS17uOBL", "sales_resource": 1934, "sales_resource_uid": "resource_eEtNhQFLlu2GDwpnZffJE", "event_group": null, "destination_address": 0, "resources": [], "cancellation_reason": "client_request", "cancellation_reason_text": "Client called to cancel", "recurrence": null } ] } } } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Insufficient permissions or missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 403, "message": "Insufficient permissions. Required scope: read-appointment", "error": "Forbidden" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v2.1/calendar/planning-guides": { "get": { "tags": [ "Planning Guides" ], "summary": "Fetch a planning guide list (V2.1)", "description": "Fetches a list of planning guides (scheduling blocks that define when a resource is available for bookings). Planning guides have `appointmentdata_calendartype = 'Guide'`.\n\nThis endpoint is designed for integrations that maintain a local copy of planning guide availability windows.\n\n## Recommended sync pattern\n\n1. **Initial backfill**: Record the current UTC timestamp before you start. Bound your window with `filter[start_at][gte]` and `filter[start_at][lte]`. Omit `filter[active][eq]` to receive both active and inactive guides in a single pass.\n2. **Incremental polling**: Use `filter[modified_at][gte]` with the timestamp recorded at the start of the backfill (not the highest `modified_at` seen in responses). This ensures records modified mid-backfill are not missed. Advance the cursor to the previous poll's start time on each subsequent poll.\n\n## Pagination\n\nPass `meta.nextToken` from the previous response as the `nextToken` query parameter to fetch the next page. When `nextToken` is absent or null there are no more pages.\n\n## Authentication\n\nRequires the `read-appointment` JWT scope.\n", "operationId": "get-calendar-planningguidesv21", "security": [ { "bearerAuth": [ "read-appointment" ] } ], "parameters": [ { "name": "filter[id][in]", "in": "query", "description": "Comma-separated list of planning guide IDs. Use for targeted batch re-fetches.\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "examples": { "Example": { "summary": "", "value": [ "2048", "2049" ] } } }, { "name": "filter[modified_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only guides modified at or after this timestamp. Use as the anchor for incremental polling.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "examples": { "Example": { "summary": "", "value": "2026-01-15T08:30:00Z" } } }, { "name": "filter[start_at][gte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only guides starting at or after this time. Combine with `filter[start_at][lte]` to define a calendar window for backfill.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "examples": { "Example": { "summary": "", "value": "2026-01-01T00:00:00Z" } } }, { "name": "filter[start_at][lte]", "in": "query", "description": "ISO 8601 datetime (inclusive). Returns only guides starting at or before this time.\n", "required": false, "schema": { "type": "string", "format": "date-time" }, "examples": { "Example": { "summary": "", "value": "2026-04-01T00:00:00Z" } } }, { "name": "filter[active][eq]", "in": "query", "description": "Filter by active status.\n- `true`: active guides only\n- `false`: inactive guides only\n- Omitted: all guides regardless of status\n", "required": false, "schema": { "type": "boolean" }, "examples": { "Example": { "summary": "", "value": true } } }, { "name": "filter[resources.uid][in]", "in": "query", "description": "Comma-separated list of resource UIDs. Returns guides assigned to any of the specified resources (vets, nurses, rooms, etc.).\n", "required": false, "schema": { "type": "array", "items": { "type": "string" } }, "style": "form", "explode": false, "examples": { "Example": { "summary": "", "value": [ "resource_iHmhFtUJBmDYB5m8rMTI0", "resource_hvy20slsY9M8886UigeIF" ] } } }, { "name": "pageSize", "in": "query", "description": "Number of guides to return per page. Defaults to 1000, maximum 5000.", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 1000 }, "examples": { "Example": { "summary": "", "value": 1000 } } }, { "name": "nextToken", "in": "query", "description": "Pagination cursor returned in `meta.nextToken` from a previous response. Omit on the first request.\n", "required": false, "schema": { "type": "string" }, "examples": { "Example": { "summary": "", "value": "AB3e7Z2i9FJu0j7hLExLp" } } } ], "responses": { "200": { "description": "Successful response with planning guide list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPlanningGuidesV21Response" }, "examples": { "withRecurrence": { "summary": "Page with a recurring and a one-time planning guide", "value": { "meta": { "nextToken": "AB3e7Z2i9FJu0j7hLExLp" }, "data": [ { "id": 2048, "uid": "appointment_uJMYy7DC3CT9MsPB0r3HU", "created_at": 1307498299, "modified_at": 1765395429, "active": true, "start_at": 1307491200, "duration": 28800, "type_id": 8, "type_uid": "appointmentType_jemy7oGJjj0BExij6D3xk", "description": "", "resources": [ { "id": 36, "uid": "resource_dC7T87I3VNJbcttDAeeID", "name": "Dr Smith", "type": "user" } ], "recurrence": { "repeat_interval": 604800, "repeat_end_at": null } }, { "id": 2049, "uid": "appointment_vKNZz8ED4DU0HtQC1s4IV", "created_at": 1307498300, "modified_at": 1765395430, "active": true, "start_at": 1307577600, "duration": 10800, "type_id": 7, "type_uid": "appointmentType_kfnz8pHKkt1CFpjk7E4yl", "description": "", "resources": [ { "id": 36, "uid": "resource_dC7T87I3VNJbcttDAeeID", "name": "Dr Smith", "type": "user" } ], "recurrence": null } ] } } } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "403": { "description": "Forbidden - Insufficient permissions or missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 403, "message": "Insufficient permissions. Required scope: read-appointment", "error": "Forbidden" } } } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/v4/calendar/availability": { "get": { "tags": [ "Availability" ], "summary": "Get resource availability", "description": "Retrieves availability information for one or more resources across specified dates.\n\nReturns time slots showing when resources are available for appointments, including:\n- Available and unavailable time slots\n- Slot duration and start times\n- Associated appointment types\n- Timezone information\n\n## Constraints\n- Maximum 5 resources per request\n- Maximum 7 dates per request\n- Dates must be within the next 6 months\n- Dates cannot be in the past\n- Duration must be between 10 and 360 minutes\n- Duration must be divisible by 5\n\n## Feature Flags\n- Supports batch processing for improved performance\n- Optional shadow testing mode for A/B testing\n- Optional caching bypass\n", "operationId": "get-calendar-availability", "security": [ { "bearerAuth": [ "read-appointment" ] } ], "parameters": [ { "name": "resources[]", "in": "query", "description": "Array of resource IDs to retrieve availability for. Maximum 5 resources per request. Resources must exist and be accessible for the authenticated site.\n", "required": true, "schema": { "type": "array", "items": { "type": "string", "pattern": "^resource_[a-zA-Z0-9]{21}$" }, "minItems": 1, "maxItems": 5, "uniqueItems": true }, "style": "form", "explode": true, "examples": { "Example": { "summary": "", "value": [ "resource_EqnQvqSxkpvEFYU7tTeFz", "resource_fQVJAx2rpoHoN9Jr4CLwZ" ] } } }, { "name": "dates[]", "in": "query", "description": "Array of dates to retrieve availability for, in ISO 8601 format (YYYY-MM-DD). Maximum 7 dates per request. Dates must not be in the past and must be within the next 6 months.\n", "required": true, "schema": { "type": "array", "items": { "type": "string", "format": "date" }, "minItems": 1, "maxItems": 7, "uniqueItems": true }, "style": "form", "explode": true, "examples": { "Example": { "summary": "", "value": [ "2025-10-24", "2025-10-25", "2025-10-26" ] } } }, { "name": "duration", "in": "query", "description": "The duration of the requested appointment slot in minutes. Must be between 10 and 360 minutes and divisible by 5. Valid examples: 10, 15, 20, 30, 45, 60, 90, 120\n", "required": true, "schema": { "type": "integer", "minimum": 10, "maximum": 360, "multipleOf": 5 }, "examples": { "Example": { "summary": "", "value": 30 } } }, { "name": "filter[slots.available][eq]", "in": "query", "description": "Filter to return only available or unavailable slots. When set to true, returns only slots where available=true. When set to false, returns only slots where available=false. When omitted, returns all slots regardless of availability.\n", "required": false, "schema": { "type": "boolean" }, "examples": { "Example": { "summary": "", "value": true } } }, { "name": "filter[slots.appointmentType.id][in]", "in": "query", "description": "Filter slots by appointment type IDs. Returns only slots that are valid for the specified appointment types. Accepts comma-separated list of appointment type IDs.\n", "required": false, "schema": { "type": "array", "items": { "type": "string", "pattern": "^appointmentType_[a-zA-Z0-9]{21}$" } }, "style": "form", "explode": false, "examples": { "Example": { "summary": "", "value": [ "appointmentType_eqh7DNX7sSRIkdOILxfnE", "appointmentType_VJa7xPp4UpURFwRJHAGVo" ] } } } ], "responses": { "200": { "description": "Successful response with availability data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAvailabilityResponse" }, "examples": { "singleResourceSingleDate": { "summary": "Single resource, single date", "value": { "data": [ { "id": "resourceAvailability_XVum98uqbORY2Hk455Saj", "type": "resourceAvailability", "attributes": { "date": "2025-10-24", "timezone": "Pacific/Auckland", "slots": [ { "start": "09:00:00.000+13:00", "duration": 30, "available": true, "relationships": { "appointmentType": { "data": [ { "type": "appointmentType", "id": "appointmentType_NFcxI0QT2Bykr5JXRhrnp" } ] } } }, { "start": "09:30:00.000+13:00", "duration": 30, "available": true, "relationships": { "appointmentType": { "data": [ { "type": "appointmentType", "id": "appointmentType_eJIxF9emWNgGEiLgH16Fc" } ] } } }, { "start": "10:00:00.000+13:00", "duration": 30, "available": false, "relationships": { "appointmentType": { "data": [] } } } ] }, "relationships": { "site": { "id": "site_krNMWpG9hTBPGMmnnj95E", "type": "site" }, "resource": { "id": "resource_4qvY7f3YVaF9wA932C22q", "type": "resource" } } } ] } }, "multipleResourcesMultipleDates": { "summary": "Multiple resources, multiple dates", "value": { "data": [ { "id": "resourceAvailability_gmUPCZZCxwOhDKotxDEbc", "type": "resourceAvailability", "attributes": { "date": "2025-10-24", "timezone": "Pacific/Auckland", "slots": [ { "start": "09:00:00.000+13:00", "duration": 15, "available": true, "relationships": { "appointmentType": { "data": [ { "type": "appointmentType", "id": "appointmentType_vxGFzKMDfBbq6u48IQNp6" } ] } } } ] }, "relationships": { "site": { "id": "site_hDMZYgNYVnHL1p1c6uu8s", "type": "site" }, "resource": { "id": "resource_6AQ8V7GUgNxLXKOhMWIAd", "type": "resource" } } }, { "id": "resourceAvailability_LqNSCIZObhNaft0vgnc59", "type": "resourceAvailability", "attributes": { "date": "2025-10-24", "timezone": "Pacific/Auckland", "slots": [ { "start": "08:00:00.000+13:00", "duration": 15, "available": true, "relationships": { "appointmentType": { "data": [ { "type": "appointmentType", "id": "appointmentType_W9o1X4EZ2iwzfhpnthRz1" } ] } } } ] }, "relationships": { "site": { "id": "site_6Tr2fo4cYpgQVhn9n3KDE", "type": "site" }, "resource": { "id": "resource_7kFA6kN9BDOoCJTc7zOyk", "type": "resource" } } } ] } } } } } }, "400": { "description": "Bad Request - Invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "pastDate": { "summary": "Past date provided", "value": { "statusCode": 400, "message": "Date 2025-10-20 is in the past", "error": "Bad Request" } }, "futureDate": { "summary": "Date too far in future", "value": { "statusCode": 400, "message": "Date 2026-05-24 is more than 6 months in the future", "error": "Bad Request" } }, "invalidDuration": { "summary": "Invalid duration value", "value": { "statusCode": 400, "message": "Duration must be divisible by 5 and between 10 and 360 minutes", "error": "Bad Request" } }, "tooManyResources": { "summary": "Too many resources requested", "value": { "statusCode": 400, "message": "resources must contain no more than 5 elements", "error": "Bad Request" } }, "tooManyDates": { "summary": "Too many dates requested", "value": { "statusCode": 400, "message": "dates must contain no more than 7 elements", "error": "Bad Request" } } } } } }, "401": { "description": "Unauthorized - Missing or invalid authentication token", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 401, "message": "Unauthorized", "error": "Unauthorized" } } } } } }, "403": { "description": "Forbidden - Insufficient permissions or missing required scope", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 403, "message": "Insufficient permissions. Required scope: read-appointment", "error": "Forbidden" } } } } } }, "404": { "description": "Resource Not Found - One or more requested resources do not exist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 404, "message": "Resource not found: resource_InvalidResourceId", "error": "Not Found" } } } } } }, "422": { "description": "Unprocessable Entity - The availability calculation timed out because the database read exceeded its time limit. Reduce the number of dates and resource combinations to lower request latency and retry.\n", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 422, "message": "The availability request timed out. Reduce the number of dates and resources, then try again.", "error": "Unprocessable Entity" } } } } } }, "429": { "description": "Too Many Requests - Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 429, "message": "Rate limit exceeded. Please try again later.", "error": "Too Many Requests" } } } } }, "headers": { "X-RateLimit-Limit": { "description": "The rate limit ceiling for the endpoint", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "The number of requests remaining in the current window", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "The time at which the current rate limit window resets (Unix timestamp)", "schema": { "type": "integer" } } } }, "500": { "description": "Internal Server Error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" }, "examples": { "Example": { "summary": "", "value": { "statusCode": 500, "message": "Internal server error occurred", "error": "Internal Server Error" } } } } } } } } } } }