--- title: "List appointment availabilities" method: POST path: "/api/business/{businessId}/branch/{branchId}/appointments/availability" tags: ["Appointment Availability"] --- # List appointment availabilities `POST /api/business/{businessId}/branch/{branchId}/appointments/availability` ## Request - Base URL: `http://api-gateway-eu.phorest.com/third-party-api-server` - URL: `http://api-gateway-eu.phorest.com/third-party-api-server/api/business/{businessId}/branch/{branchId}/appointments/availability` - Auth: HTTP basic - TypeScript: (a function with typed inputs; its response is checked against the schema) Get a list of available appointment times for the specified business id and branch id, within the specified date range for the specified services ## Path parameters - `businessId` string, required - `branchId` string, required ## Request body - AppointmentAvailabilityRequest: Details of the required appointment - `clientId` string: The unique client identifier - `startTime` string, date-time, required: The earliest time to consider an available appointment in ISO 8601 format - `endTime` string, date-time, required: The latest time to consider an available appointment in ISO 8601 format - `clientServiceSelections` ClientServiceSelection[], required: List of services, grouped by the client who selected those services, for which availability should be checked. Currently only service selections for a single client will be accepted - `clientId` string: The unique identifier of the client for which these service selections apply, if the client is known - `serviceSelections` ServiceSelection[], required: The services selected by this client - `serviceId` string, required: The unique identifier for the service - `branchServiceGroupId` string: The unique identifier of the group to which this service belongs. Applicable only if this service is part of a grouping of services for the purpose of a package or special offer - `staffId` string: The unique identifier of the staff member who has been selected to perform the service. Applicable only if there is a preference for a specific staff member to perform the service - `clientCourseId` string: The unique identifier of the client's course the service will be redeemed against. Applicable only if the service is being booked as a course session. When provided, and where course expiry enforcement is enabled, available times after the course expiry date are not returned - `rescheduleBookingId` string: The id of an existing appointment, if the request is being made to find availability in order to reschedule that existing appointment - `isOnlineAvailability` boolean: Fetch staff available online ## Response `200` Appointment availabilities listed - AppointmentAvailabilityResponse - `data` AvailableAppointment[]: List of available appointment slots from which an appointment can chosen - `startTime` string, date-time: The start time of the appointment - `clientSchedules` ClientAppointmentSchedule[]: List of the appointment schedules, grouped by client, for this appointment slot - `clientId` string: The unique identifier of the client for which this service schedule applies. Only present if the request specified the client identifier as part of the service selections - `serviceSchedules` ServiceSchedule[]: Details of the schedule for the client's chosen set of services - `serviceId` string, required: The unique identifier for the service - `startTime` string, date-time, required: The time this service would start - `endTime` string, date-time: The time this service would end - `appointmentId` string: The unique identifier of the appointment that this service is scheduled for. - `staffId` string, required: The unique identifier of the staff member who would be performing the service - `roomId` string: The unique identifier of the room where the service would be performed - `machineId` string: The unique identifier of the machine which would be used to perform this service, if applicable for the service - `branchServiceGroupId` string: The unique identifier of the group to which this service belongs. Applicable only if this service is part of a grouping of services for the purpose of a package or special offer - `serviceGroupItemOptionId` string: The unique identifier of the option within the group to which this service belongs. Applicable only if this service is part of a grouping of services for the purpose of a package or special offer - `alternativeStaffMember` boolean: Will only be set to true if a staff member was specified in the request to perform the service but a different staff member was specified in the staffId field of the response. This will happen if the preferred staff member is unable to perform the service but another suitable staff member is available - `staffRequest` boolean: Set to true if a staff member was specified in the request to perform the service - `clientCourseItemId` string: The unique identifier of the course item id. If this is passed with a booking request, the system will try to deduct the service unit from the remaining number of units in the course. - `price` number: The price of the service. If this is passed with a booking request, it will override the system price. If not sent the price will be calculated automatically using the branches configuration ## Other responses - `400`: Availability request data is invalid, unable to list appointment availabilities - `404`: Business or branch with the specified ids don't exist - `429`: Request rate limit exceeded. Current limit set to 100 rps. - `500`: An error occurred while trying to find available appointment times ## Changes - **2026-11-03** `beea6ef29634`: 1 info - added the new optional request property `clientServiceSelections/items/serviceSelections/items/clientCourseId` [Operation history](https://skmtc.dev/phorest/apis/third-party-api/changes/api/business/:businessId/branch/:branchId/appointments/availability/post.md) --- [API](https://skmtc.dev/phorest/apis/third-party-api.md) - [All operations](https://skmtc.dev/phorest/apis/third-party-api/llms.txt) - [OpenAPI document](https://skmtc.dev/phorest/apis/third-party-api/revisions/beea6ef29634?raw)