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 /appointments | Returns all appointment objects on an account in array format. |
| GET /appointmentList/report | Returns all appointment objects on an account in array format. |
| 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. |
| GET /appointments/{calendarId} | Returns a JSON object for specified appointment. |
| GET /appointments/resource/{resourceId}/{statusList} | Returns all appointment objects that include 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 specified appointment as determined by the value set in its recurringAppointmentId. |
| GET /appointments/{calendarId}/checkWaitList | Checks the waitlist of 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. |
| PUT /appointments/{calendarId} | Updates an existing appointment object. Request body/payload: Must pass an appointment object with the desired changes made. For these calls, you need to pass an appointment object with all required fields and any fields you want to update filled in the body of the payload. We have an example of an appointment 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}/{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.
| Property name | Type | Required | Writable | Description |
|---|---|---|---|---|
| addOnReasonIdList | array | Displays an array of the reasonIds for any service add-ons added for the specified appointment. | ||
| addOnReasonList | array | Displays an array of the reason names for any service add-ons added for the specified appointment. | ||
| additionalStaffIdList | array | Yes | Displays an array of the staffIds for any additional staff members you add to the specified appointment so they cannot otherwise be booked for this time slot. | |
| additionalStaffNameList | string | Yes | Displays a list of any additional staff you add to the specified appointment so they cannot otherwise be booked for this time slot. | |
| address | string | Yes | Displays the address entered during appointment creation of the specified appointment and is set to a location of locationType VARIABLE. | |
| appointmentIdHash | string | Displays a hash made from the specified appointment's ID. | ||
| appointmentDateTimeClient | string | Displays the date and time of the specified appointment as the client sees them. | ||
| appointmentDateTimeStaff | string | Displays the date and time of the specified appointment as the staff sees them. Can be different from client's view if staff has time blocked off between appointments or if staff is in a different timezone than client. | ||
| apptTZ | string | Displays the timezone that the specified appointment is scheduled for. | ||
| batchAppointmentId | integer | Provides unique numerical ID of the batch that the specified appointment is part of. | ||
| blockResourceIdList | array | Displays an array of all the resourceIds for resources that aren't allowed to be used for the specified appointment. | ||
| blockStaffIdList | array | Yes | Displays staffIds for any additional staff members you have added to the specified appointment so they cannot be otherwise booked for this time slot. Whatever IDs are added to the additionalStaffIdList are automatically added to the blockStaffIdList. The blockStaffIdList is used to automatically block off staff across child accounts in our enterprise set up model. | |
| blockedStaffList | array | Yes | Displays full staff objects for any additional staff members you have added to the specified appointment in the blockStaffIdList or additionalStaffIdList. | |
| businessId | integer | Yes | Provides unique numerical ID for the business that offers the specified appointment. | |
| calTimeSlot | string | Displays the calendar time slot that the specified appointment takes up. | ||
| calendarId | integer | Yes | Provides unique numerical ID of the specified appointment. | |
| cancelReason | string | Displays any reason given for cancelling the specified appointment. | ||
| cancelUser | string | Displays as username of staff who cancelled the specified appointment or as "WebClient" if client cancelled their own appointment. If appointment is marked as COMPLETED, the username of the staff person who marked the appointment as completed displays here. | ||
| changeReason | string | Displays any reason given for changing the specified appointment. | ||
| classScheduleId | integer | Yes | If the specified appointment is an instance of a class schedule, this field will contain the unique numerical ID for that class schedule. | |
| classroom | string | Displays as the classroom number assigned to the specified class-based appointment. | ||
| client | object | Yes | Displays the object of client who is connected to the specified appointment - for more info, see Clients API page. | |
| clientConfirmDate | integer | Yes | Displays the date in milliseconds elapsed since January 1 1970 UTC format that client was marked as confirmed for the specified appointment. | |
| clientConfirmed | boolean | Yes | Indicates whether or not the client has confirmed the specified appointment. | |
| clientEndDate | string | Yes | Displays as date the specified appointment is set to end without buffer displayed as YYYY-MM-DD. | |
| clientEndDateTime | integer | Displays as date & time that the specified appointment is set to end for the client in milliseconds elapsed since January 1 1970 UTC format. | ||
| clientEndDateTimeUTC | integer | Displays as date & time that the specified appointment is set to end for the client in milliseconds elapsed since January 1 1970 UTC format. | ||
| clientEndTime | integer | Yes | Displays as time the specified appointment is set to end without buffer displayed in military format. | |
| clientReminderHours | integer | Yes | Displays the number of hours before the specified appointment that an email reminder will be sent to the client. | |
| clientRescheduleCount | integer | Displays the number of times client has rescheduled the specified appointment. | ||
| clientStartDate | string | Yes | Displays as date the specified appointment is set to begin without buffer displayed as YYYY-MM-DD. | |
| clientStartDateTime | integer | Displays as date & time that the specified appointment is set to begin for the client in milliseconds elapsed since January 1 1970 UTC format. | ||
| clientStartDateTimeUTC | integer | Displays as date & time that the specified appointment is set to begin for the client in milliseconds elapsed since January 1 1970 UTC format. | ||
| clientStartTime | integer | Yes | Displays as time the specified appointment is set to begin without buffer displayed in military format. | |
| color | string | Yes | Displays any color chosen to override the specified appointment on the backoffice calendar. | |
| completedReason | string | Displays any note the staff may have entered while marking the specified appointment as completed. Can be injected into completed email template sent to client with tag %COMPLETED_NOTE%. | ||
| coordinatorStaff | object | Yes | Displays staff object for the staff member that was the coordinator staff for the specified appointment. The coordinator staff's schedule is not blocked. For more info, see Staff API page. | |
| coupon | object | If client enters a coupon while booking the specified appointment through the scheduler, the object of the coupon they entered will display here - for more info, see Coupon API page. | ||
| couponId | integer | Provides unique numeric ID that is stored on the coupon object for the specified appointment. | ||
| createddate | string | Displays as date the specified appointment was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | ||
| createduser | string | Displays as username of the user who created the specified appointment. If client booked appointment from scheduler would display as "WebClient". | ||
| customField1 | string | Displays as the content of the specified appointment's first custom field. | ||
| customField2 | string | Displays as the content of the specified appointment's second custom field. | ||
| customField3 | string | Displays as the content of the specified appointment's third custom field. | ||
| customFieldData | string | Displays as the content of all of the specified appointment's custom fields, combined. | ||
| customFieldDesc | string | Displays the label and value properties of any scheduler preference field objects that have the mode property set to APPT so that users can inject these into email templates with 1 centralized tag which is %CUSTOM_FIELDS%. | ||
| date | string | Yes | Yes | Provides string representation of the date the specified appointment is taking place displayed as YYYY-MM-DD. If using startDate, endDate, clientStartDate, and clientEndDate are not filled for some reason, this is used for scheduling purposes. |
| dateCheckedIn | integer | Yes | Displays as date the client checked in to the specified appointment. | |
| dateCompleted | integer | Displays as date the specified appointment was completed. | ||
| dateStarted | integer | Displays as date the specified appointment was marked as substatus of INPROGRESS. | ||
| discount | integer | If coupon was applied to the specified appointment, this displays as the total dollar value that was taken off the price of the service/class booked for. | ||
| duration | integer | Provides the duration of the specified appointment in minutes. | ||
| endDate | string | Yes | Yes | Provides the date that the specified appointment ends with buffer time alloted displayed as YYYY-MM-DD. |
| endDateTimeUTC | integer | Displays as date & time that the specified appointment is set to end in milliseconds elapsed since January 1 1970, UTC format. | ||
| endTime | integer | Yes | Yes | Provides the end time of the specified appointment accounting for any buffer on the reason displayed in military format. |
| externalEventId | integer | Provides unique numeric ID of any external events linked to the specified appointment. | ||
| fields | array | Yes | Displays an array of any scheduler field objects that were assigned to the specified appointment - for more info, see the Scheduler Field API page. | |
| invitationUUId | string | If you invite a client to book with you from the clients menu (selecting a client and clicking to send email) and in the invitation template that you send out you have the tag %BOOK_INVITATION_URL%, then when the client clicks the link after receiving the invitation they will be directed to a scheduling landing page with the invitationUUId attached at the end of it. If the client books, we set the invitationUUId from the invitation sent out to the appointment object. This allows us to map the lifecycle of an invitation campaign as shown under Messaging > Monitor Campaigns so we can know if an invitation that was sent out resulted in a booked appointment | ||
| jobRequisitionId | integer | Yes | Provides unique numeric ID of the specified appointment's job requisition number. | |
| location | object | Yes | Yes | Displays the location object assigned to the specified appointment - for more info, see Locations API page. |
| locationGroup | object | Yes | If you assign the specified appointment to a specific location group, then this would be the object of that location group - for more info, see Groups API page. | |
| locationSuperGroup | object | Yes | If you assign the location group of the specified appointment to a specific location super group, then this would be the object of that location super group - for more info, see Groups API page. | |
| manageApptUrl | string | Displays as the URL that the client can go to to make changes to the specified appointment using the web scheduler. | ||
| modifieddate | integer | Displays as date the specified appointment was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | ||
| modifieduser | string | Displays as username of user who last modified the specified appointment. If client on web scheduler was last to modify then it would be displayed as "WebClient". | ||
| noPrefSelected | boolean | Yes | Indicates whether or not no preference has been selected for the specified appointment. | |
| noShowReason | string | Displays as reason given for a no show for the specified appointment. | ||
| note | string | Yes | Displays as note added to the specified appointment's profile in default comments field. | |
| packageSoldId | integer | Yes | Displays as unique numerical ID of package used to redeem for the specified appointment. | |
| paid | boolean | Indicates whether or not the specified appointment has been paid for yet. | ||
| price | integer | Yes | Displays as price set for the specified appointment after adjusting for any coupons that may have been used. | |
| reason | object | Yes | Displays the reason object connected to the specified appointment - for more info, see Services API page. | |
| reasonBatchSeriesId | integer | Provides unique numerical ID of the reason batch that the specified appointment is part of. | ||
| reasonDesc | string | Displays as the description provided for the reason of the specified appointment. | ||
| reasonGroup | object | Yes | If you assign the reason of the specified appointment to a specific reason group, then this would be the object of that reason group - for more info, see Groups API page. | |
| recall | object | If a recall campaign has been set up that impacts the specified appointment, then the object of the recall campaign that the appointment is a part of shows here. | ||
| recallDate | integer | Displays as goal date for the specified appointment's recall appointment as determined by the recall object that the appointment is set to. Shows as milliseconds elapsed since January 1, 1970 00:00:00 UTC form. | ||
| recallStatus | string | Displays as status of recall of the specified appointment if applicable. | ||
| recurringAppointmentId | integer | If the specified appointment is part of a repeating appointment series, then this provides unique numerical ID of repeating appointment series. | ||
| remindClientSmsHours | integer | Yes | Displays the number of hours before the specified appointment that an SMS reminder will be sent to the client. | |
| remindStaffSmsHours | integer | Yes | Displays the number of hours before the specified appointment that an SMS reminder will be sent to the staff. | |
| resource | object | Yes | Displays any resource object connected to the specified appointment - for more info, see Resources API page. | |
| seats | integer | Yes | Provides number of seats for the specified appointment. Only applicable for reasonType of CLASS where if this number is greater than 1 it would take up as many attendees slots as this number indicates in the class schedule. | |
| sendConfirmationToClient | boolean | Yes | Indicates whether or not a confirmation email should be sent to client on recurring appointment POST or PUT. If set to TRUE, then when the specified appointment is created or changed the confirmation will get sent out. | |
| sendConfirmationToStaff | boolean | Yes | Indicates whether or not a confirmation email should be sent to staff on recurring appointment POST or PUT. If set to TRUE, then when the specified appointment is created or changed the confirmation will get sent out. | |
| showAs | string | Displays the status that the specified appointment will show as. | ||
| staff | object | Yes | Yes | Displays the staff object for staff member connected to the specified appointment - for more info, see Staff API page. |
| staffReminderHours | integer | Yes | Displays the number of hours before the specified appointment that an email reminder will be sent to the staff. | |
| staffRescheduleCount | integer | Displays the number of times staff has rescheduled the specified appointment. | ||
| staffTimeText | string | Displays the specified appointment's start time & date as a string of text. | ||
| startDate | string | Yes | Yes | Provides the date the specified appointment starts with buffer displayed as YYYY-MM-DD. |
| startDateTimeUTC | integer | Displays as date & time that the specified appointment is set to begin in milliseconds elapsed since January 1 1970, UTC format. | ||
| startTime | integer | Yes | Yes | Provides the time the specified appointment starts displayed in military format. |
| status | string | Yes | Displays the status of the specified appointment. Has acceptable values PENDING, OPEN, NO_SHOW, COMPLETED, CANCELLED, DELETED. | |
| subStatus | string | Yes | Displays the substatus of the specified appointment. Substatuses can be customized on Business and Enterprise level accounts, but default substatus values include: PENDING, PENDING_CONFIRMATION, PENDING_WAITLIST, OPEN, CONFIRMED, CHECKEDIN, INPROGRESS, COMPLETED, NO_SHOW, CANCELLED, DELETED. | |
| subject | string | Displays as the subject of the specified appointment. | ||
| tax1Amount | string | Displays as the tax amount charged for the specified appointment. | ||
| ticket | string | Displays as the ticket of the specified appointment. | ||
| transactionFee | string | Displays as fee added to transaction added for the specified appointment. | ||
| waitListId | integer | Yes | If the specified appointment was created by claiming a seat from a waitlist registration, this provides the unique numerical id of the waitlist registration the appointment was claimed from. To create an appointment for a client that is already on a waitlist, you will want to set the waitListId property on the appointment object to that on the waitlist object from which you are creating the new appointment. This will cause the status property on that waitlist object to be set to BOOKED. |
To add an appointment to the TimeTap database, you'll need to POST a filled out Appointment JSON object to the "/appointments" endpoint appended to one of the URI prefixes listed on the Introduction page.
A general outline of the steps goes as follows:
- Model the Appointment JSON object in your chosen language/platform
- Fill in the required values (listed below)
- Convert model object to JSON format
- Send filled-in Appointment JSON object via POST request to "/appointments" endpoint
A successful POST will receive a response Appointment JSON object mirroring the object you posted. An unsuccessful POST will receive standard HTML error codes.
For more information on adding appointments via the appointments API, see our Webhooks guide.
Please note: for date and time properties, you do not need to do time zone conversion between the client and the staff. Pass the dates and times as you want them set in the staff's time zone and the backend will take care of converting them for the client's timezone in the messages that are sent to the client
Properties/Objects | Required | Type | Details |
|---|---|---|---|
| businessId | true | number | This is generally your API key. |
| location | true | object | Must include at least the locationId as part of the object passed. |
| locationGroup | false | object | Must include at least the groupId as part of the object passed. |
| staff | true | object | Must include at least the professionalId as part of the object passed. |
| reason | true | object | Must include at least the reasonId as part of the object passed. |
| reasonGroup | false | object | Must include at least the groupId as part of the object passed. |
| client | false | object | Must include at least the clientId as part of the object passed. |
| fields | false | array of objects | In the process of saving the appointment you can make a call to GET schedulerFieldList/reason/{reasonId}passing the id of the selected reason. The returned array will have a list of all fields that are compatible with the reason selected in the booking process. If you loop through those fields, any field objects whose "mode" property is set to "APPT" (meaning appointment fields) and not assigned to "CLIENT" can be passed into this fields array property as the appointment's custom fields. The objects that fill the array need to have the schedulerPreferenceFieldDefnId property filled in, the value filled in, as well as the businessId. |
| clientStartDate | true | string | This is the start date of the appointment for the client. Should be formatted as YYYY-MM-DD. |
| clientEndDate | true | string | This should be set to the end date of the appointment for the client. Most of the time this is the same as the clientStartDate, but if the appointment eclipses midnight and ends on a different date, you would need to pass the different date in this field. Should be formatted as YYYY-MM-DD. |
| startDate | true | string | This is the start date of the appointment for the staff. It is possible (with buffers on services) that the appointment blocks off a different range of dates and times for the staff than the client. For instance, an appointment is an hour long in duration but has a 30 minute buffer before. If the appointment starts at 12:15am on June 1st, 2018 for the client, then for the staff it would start at 11:45pm on May 31st, 2018. While the clientStartDate would get passed as 2018-06-01, the startDate should get passed as 2018-05-31. |
| endDate | true | string | This is the end date of the appointment for the staff with similar possibilities to the startDate line item listed above. For instance, an appointment is an hour long in duration but has a 30 minute buffer after. If the appointment starts at 10:45pm on May 31st, 2018 for the client, then for the client it would end at 11:45pm on May 31st, but for the staff it would end at 12:15am on June 1st 2018. While the clientEndDate would get passed as 2018-05-31, the startDate should get passed as 2018-06-01. |
| clientStartTime | true | number | This is the start time of the appointment for the client. Should have military time format. Formatting examples:
|
| clientEndTime | true | number | This is the end time of the appointment for the client. Generally you use the duration of the selected service (i.e. reason) to determine this based off of the clientStartTime. Should be formatted as YYYY-MM-DD. |
| startTime | true | number | This is the start time of the appointment for the staff. Should be formatted the same as the clientStartTime defined above. Generally this is calculated based on the bufferBefore property set on the selected service/reason. So if an appointment is set to start for the client at 2:00pm but the selected service has a 15 minute bufferBefore value set then the startTime should get set as 1345 (1:45pm). Please note: You can create an appointment by passing the appointment object with this value set to null. If you do this, the backend will automatically set the property based off the selected reason's bufferBefore value. If the bufferBefore value is null, then the startTime will be set to the same value as the clientStartTime. |
| endTime | true | number | This is the end time of the appointment for the staff. Should be formatted the same as the clientStartTime defined above. Generally this is calculated based on the bufferAfter property set on the selected service/reason. So if an appointment is set to end for the client at 2:00pm but the selected service has a 15 minute bufferAfter value set then the endTime should get set as 1415 (2:15pm). Please note: You can create an appointment by passing the appointment object with this value set to null. If you do this, the backend will automatically set the property based off the selected reason's bufferAfter value. If the bufferAfter value is null, then the endTime will be set to the same value as the clientEndTime. |
| classScheduleId | true (if selected reason is of reasonType class) | number | If you are adding an appointment for a class session, you have to pass the classScheduleId of the class session you are wanting to put the client into. It is not enough to just pass the date and time of the session to map the client to that session as there could be multiple sessions scheduled for the same date and time at the same location with the same staff for the same reason. |
| clientReminderHours | true | number | This is the number of hours before the appointment that you want the reminder email to be sent to the client. If you do not want to send an email reminder to the client, set the value to 0. Otherwise, set it to the hour value. Formatting examples
|
| staffReminderHours | true | number | This is the number of hours before the appointment that you want the reminder email to be sent to the staff. Same formatting rules apply here as apply to the clientReminderHours. |
| remindClientSmsHrs | true | number | This is the number of hours before the appointment that you want the reminder text message to be sent to the client. Same formatting rules apply here as apply to the clientReminderHours. |
| remindStaffSmsHrs | true | number | This is the number of hours before the appointment that you want the reminder text message to be sent to the staff. Same formatting rules apply here as apply to the clientReminderHours. |
| sendConfirmationToClient | true | boolean | If you want the New Appointment by Staff email to send out the the client upon saving the appointment, set this to true. Otherwise, set it to false. |
| sendConfirmationToStaff | true | boolean | If you want the New Appointment email to send out to the staff upon saving the appointment, set this to true. Otherwise set it to false. |
| status | true | string | Accepted values:
|
| pendingConfirmation | false | boolean | If going through the pending confirmation process for an appointment, set this value to true. Otherwise, no need to pass. |
| resource | false | object | If you have added resources to your account to use, you can make a call while creating the appointment to GET resource/location/{locationId}/reason/{reasonId} Where you pass the locationId of the selected location from the location object and the reasonId of the selected reason from the reason object. This is mostly for service based appointments because class based appointments will have the resource tied to the class session already. You'll receive a list of resources associated with the location and reason as a return from that GET call and if you want to tie one to the appointment you can set the resource property of the appointment to that selected resource. Make sure to include at least the resourceId in the passed object. To check whether the selected resource is available during the date and time that you are trying to put it in for, make a call to GET resource/{resourceId}/isBusy/{apptDate}/{startTime}/{endTime}Pass the resourceId of the selected resource, the date of the appointment (formatted as YYYY-MM-DD), the start time of the appointment (either the clientStartTime or startTime, whichever is earlier) and the end time of the appointment (either the clientEndTime or the endTime, whichever is later). That will return false if the resource is available and true if the resource is busy (meaning it is already in use for another appointment or a class session). |
| packageSoldId | false | number | Set to value of selected package that you would like to use for the appointment. |
To use our round robin logic in order to assign staff to an appointment as it gets created, you will need to make a call to the POST /appointments endpoint with a few modifications. First, in the body/payload of the POST /appointments call, you will need to pass a staff object that has the professionalId object set to null. You will also need to pass a property called "calTimeSlot" in the body/payload, which will be filled with one of the timeslots returned in the timeslots array property that gets returned from the GET /availability/{YYYY}/{MM}/{DD} call. The timeslot that that you fill in the calTimeSlot property will contain an array called units, which will contain all of the various professionalId options and gets used to assign the staff using the round robin logic.
So that you can see what I am referencing here in terms of formatting, I have included a sample JSON payload for the POST /appointments API call:
Add Comment