Appointments
These are the endpoints that are available under the /appointments path, which lists all the different appointments you have scheduled on your business' calendar.
Endpoint | Description |
---|---|
GET /appointmentList/report | Returns all appointment objects on an account in array format. NOTE: Requires paginated results. The pageNumber and pageSize parameters are required, if they are not provided they will be set to a default of pageNumber = 1 and pageSize = 25. |
GET /appointmentList/reportWithCount | Returns an object that contains a list of appointments along with a count of the total number of appointments that match the parameters passed with the call. NOTE: Requires paginated results. The pageNumber and pageSize parameters are required, if they are not provided they will be set to a default of pageNumber = 1 and pageSize = 25. |
GET /appointments/{calendarId} | Returns a JSON object for the specified appointment. |
GET /appointments/resource/{resourceId}/{statusList} | Returns all appointment objects that include the specified resource in array format. |
GET /appointments/recurringappointments/{recurringApptId} | Returns an array of appointment objects that were part of the recurring appointment series that contains the specified appointment as determined by the value set in its recurringAppointmentId. |
GET /appointments/{calendarId}/checkWaitList | Checks the waitlist of the specified appointment before updating appointment object. To send an invitation out to a waitlist registrant to claim a cancelled appointment, make this call and select which candidates that return you want to invite to claim it. You then take the waitListIds from each of those registrations and pass them in the waitListIds parameter of the PUT /appointments/{calendarId}/cancel/{sendStaffEmail}/{sendClientEmail} to place a hold event on your calendar that will stay until either the client claims it or the allotted time frame has elapsed. |
POST /appointments | Creates a new appointment object on an account. Request body/payload: Must pass an appointment object. For these calls, you need to pass an appointments object with all required fields and any fields you want to set filled in the body of the payload. We have an example of an appointments object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
POST /appointments/quickAdd | Creates a new blocking appointment object on an account. Request body/payload: Must pass a limited appointment object. For these calls, you need to pass an appointments object with all required fields and any fields you want to set filled in the body of the payload. We have an example of an appointments object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
PUT /appointments/{calendarId} | Updates an existing appointment object. Request body/payload: Must pass an appointment object with the desired changes made. For this call, you can a limited appointment object defined below. 2. professionalId 3. startDate 4. startTime 5. endDate 6. endTime NOTE: These fields will be overridden with hard coded data: 2. status 3. subject |
PUT /appointments/{calendarId}/{status}/{subStatus} | Updates the specified appointment's status & substatus. This call simply offers a generic method to update the status of an appointment instead of using a specific one. |
PUT /appointments/{calendarId}/cancel/{sendStaffEmail}/{sendClientEmail} | Sets an appointment to a substatus of CANCELLED and alters the boolean property accordingly to notify the client via email. Effectively cancels an appointment with the option to send an email to the staff and the client. To send an invitation out to a waitlist registrant to claim a cancelled appointment, make a GET /appointments/{calendarId}/checkWaitList call and then take the waitListIds from the returning waitlist objects that you want to invite and pass them in the waitListIds parameter of this call. This will place a waitlist hold event on your calendar that will stay until either the client claims it or the allotted time frame has expired. The waitlist hold is just an appointment without a client assigned to it. If you wish to remove this waitlist hold before a client claims it or the allotted time frame has expired you can use this endpoint to update the appointment and set the appointment object's status and substatus to CANCELLED. Request body/payload: Optionally, you may pass a json payload with reason and substatus { "reason": "", "subStatus": "CANCELLED" } |
PUT /appointments/{calendarId}/noshow/{sendClientEmail} | Sets an appointment to a substatus of NO_SHOW and alters boolean flag accordingly to notify the client via email. Request body/payload: Optionally, you may pass a json payload with reason and substatus { "reason": "", "subStatus": "NO_SHOW" } |
PUT /appointments/{calendarId}/completed/{sendClientEmail} | Sets an appointment to a substatus of COMPLETED and alters boolean flag accordingly to send a thank you email to the client. Request body/payload: Optionally, you may pass a json payload with reason and substatus { "reason": "", "subStatus": "COMPLETED" } |
GET/POST /appointmentList/reportCount | Returns number of appointments based on the parameters that get passed. Acceptable parameters can be found in the Appointments API Parameters section. |
GET/POST /appointmentList/reportCountsByStatus | Returns number of appointments based on the parameters that get passed for each appointment status that gets passed in the statusList parameter. Accepts the same parameters as the GET/POST /appointmentList/reportCount endpoint, looking at reasonIdList, locationIdList and staffIdList in particular. |
Data points passed on in the request URL portion of the API call that are used to filter the data being requested. To aid with page load time, we have included pageNumber and pageSize parameters for server side pagination. The pageSize parameter will be the number of items shown per page.
Parameter | Type | Endpoints to be used with | Description |
---|---|---|---|
calendarIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of calendarIds connected to the appointments to be returned following the API call. |
classScheduleId | integer | GET /appointments/report | Should be set as the unique numeric ID of client of appointment to be returned following the API call. |
classScheduleIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of classScheduleIds connected to the appointments to be returned following the API call. |
clientId | integer | GET /appointments/report | Should be set as the ID of client of appointment to be returned following the API call. |
clientIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of the clientIds connected to the appointments to be returned following the API call. |
couponIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus | Should be set as a comma-separated list of couponIds connected to the appointments to be returned following the API call. |
dateRangeType | string | GET/POST /appointmentList/report | Can be set to a value of 'createdDate' or 'modifiedDate' and works with startDate and endDate parameters to filter the appointments returned following the API call based on those properties. |
endDate | string | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as the end date of appointments to be returned following the API call, formatted as YYYY-MM-DD. |
excludeTimeOff | boolean | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | If set to TRUE then the API call does not return appointments that are set for reasons of reasonType PERSONAL; if set to FALSE then it does return appointments that are set for reasons of reasonType PERSONAL. |
locationIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of locationIds connected to the appointments to be returned following the API call. |
locationGroupIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of locationGroupIds connected to the appointments to be returned following the API call. |
onlyTimeOff | integer | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Can be set to 0 or 1; if set to 0 then reads as essentially false; if set to 1 then only appointments that are set for reasons that are of reasonType PERSONAL will return following the API call. |
order_field | string | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report | Should be set as the field that appointments returned following the API call should be ordered by. |
order_mode | string | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report | Should be set as the mode ('asc'ending or 'desc'ending) in which appointments returned following the API call should appear. |
override | boolean | POST /appointments | Can be set to 0 or 1; if set to 0 then staff for specified appointment is free during that time slot; if set to 1 you are overriding the staff's work schedule and effectively double booking him or her. |
packageSoldIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of packageSoldIds connected to the appointments to be returned following the API call. |
pageNumber | integer | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report | Works with the pageSize parameter to determine how appointments get returned following the API call. The pageNumber value represents the number of pages on which the appointments that get returned appear. |
pageSize | integer | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report | Works with the pageNumber parameter to determine how appointments gets returned following the API call. The pageSize value represents the number of appointments appearing on each page that gets returned. |
reasonIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of reasonIds connected to the appointments you want returned following the API call. This parameter is optional - if it is not sent in then the return results will include all reasons (except reasonTypes of PERSONAL if the excludeTimeOff property is set to false). |
recurringApptIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of recurringApptIds connected to the appointments to be returned following the API call. |
resourceIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of resourceIds connected to the appointments to be returned following the API call. |
showApptTz | boolean | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report | Determines whether or not the apptTz field will be filled when making this API call. |
showClientForms | boolean | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET /appointments/report | Should be set as TRUE or FALSE depending on whether or not the appointments to be returned following the API are set to show client forms. |
staffIdList | integer array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of unique numeric IDs of staff of appointments to be returned following the API call. |
startDate | string | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as the start date of appointments to be returned following the API call, formatted as YYYY-MM-DD. |
statusList | string array | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as a comma-separated list of statuses of the appointments you want returned following the API call. Has acceptable values OPEN, CLOSED, INPROGRESS, COMPLETED, READ_ONLY, PENDING, PENDING_CONFIRMATION, PENDING_WAITLIST, CHECKEDIN, CANCELLED, and CONFIRMED. |
uninvoiced | boolean | GET/POST /appointmentList/reportWithCount GET/POST /appointmentList/report GET/POST /appointmentList/reportCount GET/POST /appointmentList/reportCountsByStatus GET /appointments/report | Should be set as TRUE or FALSE depending on whether or not the appointments to be returned following the API are invoiced. |
waitListIds | integer array | PUT /appointments/{calendarId} | Should be set as a comma-separated list of waitListIds to be invited to claim the spot of a cancelled appointment. |
The objects below represent the minimum viable objects to pass that are needed to create or update an appointment object. Check whether or not a property can be written to by looking at the Object Values table below to see if the property is writable.