Page Comparison

AnchortopOfPagetopOfPage

Anchor

	topOfPage
	topOfPage

The Time Off API is used to access, create, and modify the periods of time off taken on your business' account. The Appointments Time Off API is connected to the Locations, Staff API, Services, and Resources APIs as appointments include all of those APIs. Since appointments are the main way your business will make money, it is crucial for you to familiarize yourself with how to get, create, and update the different appointments on your accountas periods of time off are taken by and only apply to staff, whereas the Vacations API is used to close a location for a company-wide period of time off.

Info

title	On this page

Table of Contents

Endpoint

Description

GET /appointments/status/{status}

Returns an array of appointments with specified status.

GET /appointments/{appointmentId}Returns a JSON object for specified appointment.GET /appointments/resource/{resourceId/{statusList}Returns all appointments that include specified resource.GET /appointments/recurringappointments/{recurringApptId}

Returns a list of appointment objects that were part of the recurring appointment series that specified appointment is part of as determined by the value set in its recurringAppointmentId.

GET /appointments/{appointmentId}/checkWaitListChecks the waitlist of specified appointment before updating appointment object.GET /appointments/reportReturns an array of all appointments on a business' account.POST /appointmentsCreates a new appointment on a business

These are the endpoints that are available under the /timeOff path, which shows what hours your staff has taken off. Please note that to create new periods of time off, you POST to the /timeOffBulk path, and also note that you can view multiple time offs by simply posting a GET call to the /appointments/report path with the excludeTimeOff parameter set to false and the onlyTimeOff parameter set to 1. For more information about GET /appointments/report calls, please refer to the Appointments API page.

Parameter

TypeEndpoints to be used with

Description

clientId

integerGET /appointments/report

Displays unique numeric ID of client of appointment to be returned following a GET report call.

classScheduleIdintegerGET /appointments/reportDisplays unique numeric ID of client of appointment to be returned following a GET report call.endDatestringGET /appointments/reportDisplays the end date of appointments to be returned following a GET report call, formatted as YYYY-MM-DD. excludeTimeOffbooleanGET /appointments/reportIf TRUE then the GET report call does not return appointments that are set for reasons of reasonType PERSONAL; if FALSE then it does return appointments that are set for reasons of reasonType PERSONAL.onlyTimeOffintegerGET /appointments/reportCan 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.order_fieldstringGET /appointments/reportDisplays the field that appointments returned following a GET report call should be ordered by.order_modestringGET /appointments/reportDisplays the mode ('asc'ending or 'desc'ending) in which appointments returned following a GET report call should appear.pageNumberintegerGET /appointments/reportWorks with the pageSize parameter to determine how appointments get returned following a GET report call. The pageNumber value represents the number of pages on which the class sessions that get returned appear.pageSizeintegerGET /appointments/report

Works with the pageNumber parameter to determine how appointments gets returned following a GET report call. The pageSize value represents the number of class sessions appearing on each page of class sessions that gets returned.

staffIdListintegerGET /appointments/reportDisplays a comma-separated list of unique numeric IDs of staff of appointments to be returned following a GET report call.startDatestringGET /appointments/reportDisplays the start date of appointments to be returned following a GET report call, formatted as YYYY-MM-DD. locationIdListintegerGET /appointments/reportDisplays a comma-separated list of locationIds connected to the appointments you want returned following a GET report call.statusListstring GET /appointments/reportDisplays a comma-separated list of statuses of the appointments you want returned following a GET report call. Has acceptable values of OPEN, CLOSED, INPROGRESS, COMPLETED, READ_ONLY, PENDING, PENDING_CONFIRMATION, PENDING_WAITLIST, CHECKEDIN, CANCELLED, and CONFIRMED. waitListIdsstring

PUT /appointments/{appointmentId}

Displays a comma-separated list of waitListIds to be invited to claim the spot of a cancelled appointment.overrideintegerPOST /appointmentsCan 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.

Code Block

language	js
title	GET /appointments/{appointmentId}
linenumbers	true
collapse	true

{ "additionalStaffIdList

Sets an appointment to a substatus of NO_SHOW and alters boolean flag accordingly to notify the client via email.

Request body/payload: Must pass an appointment object with substatus set to NO_SHOW.

This endpoint also requires a JSON POST body of an empty string for the Reason property of the appointment:

Endpoint	Description
GET /appointments/report	Returns all appointment objects on an account in array format. To get time offs to return, set the excludeTimeOff parameter to false and set the onlyTimeOff parameter to 1.
GET /timeOff/{timeOffId}	Returns a JSON object for specified time off.
POST /timeOffBulk	Creates a new timeOff object on an' account. Request body/payload: Must pass a full appointment	PUT /appointments/{appointmentId}/cancel/{sendStaffEmail}/{sendClientEmail}	Sets an appointment to a substatus of CANCEL and alters boolean flag accordingly to notify the client via email. Effectively cancels an appointment with the option to send an email to the staff and the client. timeOff object.
PUT /appointments/{appointmentId}	Updates an existing appointment. Request body/payload: Must pass an appointment with the desired changes made.
For these calls, you need to pass a timeOff object with all required fields and any fields you want to set filled in the body of the payload. We have an example of a timeOff object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.
PUT /timeOff/{timeOffId}	Updates an existing time off object. Request body/payload: Must pass an appointment a timeOff object with substatus set to CANCEL.	PUT /appointments/{appointmentId}/noshow/{sendClientEmail}

Code Block
{"reason" : ""}

PUT /appointments/{appointmentId}/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: Must pass an appointment object with substatus set to COMPLETED.

This endpoint also requires a JSON POST body of an empty string for the Reason property of the appointment:

Code Block
{"reason" : ""}

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.

the desired changes made.

For these calls, you need to pass a timeOff object with all required fields and any fields you want to update filled in the body of the payload. We have an example of a timeOff object in the responses section below and have indicated the required fields in the object values table at the bottom of this page.

DELETE /timeOff/{timeOffId}

Removes a timeOff object from view by setting its active property to false.

There are no parameters included with time off calls.

How to Get List of Time Offs

The timeOff object is just a stripped down version of the appointment object, as both are representative of events on a staff member's schedule. The timeOffId is generally interchangeable with the calendarId in the appointments API documentation. There is no dedicated endpoint to get a list of timeOff objects, but because of the relationship between time offs and appointments, you can use the appointments endpoint GET appointments/report to retrieve a list of time offs. The three things you would need to make sure of before trying to do this are:

You set the parameter onlyTimeOff to 1
The parameter excludeTimeOff is set to false
the serviceIdList parameter is either sent in as null or only includes ids for reasons that are of reasonType PERSONAL

The objects below represent the minimum viable objects to pass that are needed to create or update a timeOff 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.

Code Block

language	js
title	POST /timeOffBulk
linenumbers	true
collapse	true

{
    "appliesTo": "staff",
    "assignedTo": "select",
    "businessId": "43111",
    "endDate": "2019-02-13",
    "endTime": "1400",
    "reason": {Reason object for reason of time off - for more info, see Services API page},
    "repeats": false,
    "staffId": [
        0: 80891
    ],
    "startDate": "2019-02-13",
    "startTime": "1300"
}

Code Block

language	js
title	PUT /timeOff/{timeOffId}
linenumbers	true
collapse	true

{
    "appliesTo": "staff",
    "businessId": 43111,
    "changeReason": null,
    "appointmentDateTimeClientclientEndTime": "1400"Thursday,
Jul 26, 2018 at 8"clientStartTime":00 AM FNT"1100",
    "appointmentDateTimeStaffcolor": "Thursdaynull,
Jul 26, 2018 at 8"createdDate":00 AM FNT "2019-02-11 17:27:08",
    "blockStaffIdListcreatedUser": []"JoeSchmo",
    "blockedStaffListdescription": [],"Babysitter got    "businessId": 43111sick",
    "calendarIdendDate": 16902079"2019-02-13",
    "cancelReasonendTime": null"1400",
    "cancelUsermodifiedDate": null"2019-02-11 17:27:08",
    "changeReasonmodifiedUser": "JoeSchmo",
    "classScheduleIdnote": null"Babysitter got sick",
    "clientreason": {ClientReason object for clientreason of appointment-time off - for more info, see clientsServices API page},
    "clientConfirmedDaterecurringAppointmentId": 1532371154462null,
    "clientConfirmedstaff": true,
    "clientEndDate": "2018-07-25",
    "clientEndTime": 900{Staff object for staff of time off - for more info, see Staff API page},
    "clientReminderHoursstaffId": 180891,
    "clientRescheduleCountstartDate": 0"2019-02-13",
    "clientStartDatestartTime": "2018-07-261300",
    "clientStartTimestatus": 800"OPEN",
    "colortimeOffId": "#668CD9",
    "completedReason": null,20050788
}

Code Block

language	js
title	GET /timeOff/{timeOffId}
linenumbers	true
collapse	true

{
    "coordinatorStaffbusinessId": null43111,
    "couponchangeReason": null,
    "couponIdcolor": null,
    "createddatecreatedDate": "2018-0608-2103 14:4539:5238",
    "createdusercreatedUser": "JoeSchmo",
    "customFieldDescdescription": "CommentsNeed :a Boobreak!",
    "dateendDate": "2018-0710-2601",
    "dateCheckedInendTime": null1200,
    "dateCompleted": null,
    "discount": null,
    "endDatemodifiedDate": "2018-08-07-26",
    "endTime": 930 15:10:27",
    "fields": {Scheduler fields object for fields of fields of appointment-see scheduler fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment-see locations API page},
    "locationGroup": {Location group object for location group of appointment-see groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment-see services API page},
    "reasonGroup": {Reason group object for reason group of appointment-see groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 2,
    "remindStaffSmsHours": 4,
    "resource": {Resource object for resource of appointment-see resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment-see staff API page},
    "staffReminderHours": 3,
    "staffRescheduleCount": 9,
    "startDate": "2018-07-26",
    "startTime": 945,
    "status": "OPEN",
    "subStatus": "CONFIRMED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	GET /appointments/recurringappointments/{recurringappointmentId}
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jun 28, 2018 at 8:00 AM FNT",
    "appointmentDateTimeStaff": "Thursday, Jun 28, 2018 at 8:00 AM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": null,
    "businessId": 43111,
    "calendarId": 16902075,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": "",
    "classScheduleId": null,
    "classroom": null,
    "client": {Client object for client of appointment-see clients API page},
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": true,
    "clientEndDate": "2018-06-28",
    "clientEndTime": 900,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-06-28",
    "clientStartTime": 800,
    "color": "#668CD9",
    "completedReason": null,
    "coordinatorStaff": {Staff object for coordinator staff of appointment-see staff API page},
    "coupon": null,
    "couponId": null,
    "createddate": "2018-06-21 14:45:51",
    "createduser": "JoeSchmo",
    "customFieldDesc": "".
    "date": "2018-06-28",
    "dateCheckedIn": null,
    "dateCompleted": 1530785153340,
    "discount": null,
    "endDate": "2018-06-28",
    "endTime": 900,
    "fields": null,
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment-see locations API page},
    "locationGroup": {Location group object for location group of appointment-see groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment-see services API page},
    "reasonGroup": {Reason group object for reason group of appointment-see groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 0,
    "remindStaffSmsHours": 0,
    "resource": {Resource object for resource of appointment-see resources API page},
    "seats": 1,
    "sendConfirmationToClient": true,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment-see staff API page},
    "staffReminderHours": 0,
    "staffRescheduleCount": 0,
    "startDate": "2018-06-28",
    "startTime": 800,
    "status": "COMPLETED",
    "subStatus": "COMPLETED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	GET /appointments/resource/{resourceId}/{statusList}
linenumbers	true
collapse	true

[{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "appointmentDateTimeStaff": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 17246703,
    "cancelReason": "",
    "cancelUser": "JoeSchmo",
    "changeReason": "",
    "classScheduleId": null,
    "client": null,
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": false,
    "clientEndDate": "2018-07-26",
    "clientEndTime": 1330,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-07-26",
    "clientStartTime": 1200,
    "color": null,
    "completedReason": "",
    "coordinatorStaff": {Staff object for coordinator staff of appointment-see staff API page},
    "coupon": null,
    "couponId": null,
    "createddate": "2018-07-24 16:10:52",
    "createduser": "JoeSchmo",
    "customFieldDesc": "".
    "date": "2018-07-26",
    "dateCheckedIn": null,
    "dateCompleted": 1530785153340,
    "dateStarted": 1532525579100,
    "discount": null,
    "endDate": "2018-07-26",
    "endTime": 1325,
    "fields": {Scheduler field object for field of appointment-see scheduler fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment-see locations API page},
    "locationGroup": {Location group object for location group of appointment-see groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": "",
    "note": "",
    "packageSoldId": null,
    "price": 8,
    "reason": {Reason object for service of appointment-see services API page},
    "reasonGroup": null,
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": null,
    "remindClientSmsHrs": 1,
    "remindStaffSmsHours": 0,
    "resource": {Resource object for resource of appointment-see resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment-see staff API page},
    "staffReminderHours": 0,
    "staffRescheduleCount": 6,
    "startDate": "2018-07-26",
    "startTime": 1115,
    "status": "COMPLETED",
    "subStatus": "INPROGRESS",
    "transactionFee": null,
    "waitlistId": null
}]

Code Block

language	js
title	POST /appointments
linenumbers	true
collapse	true

{
    "classScheduleId": null,
    "client": {Client object for client of appointment-see clients API page},
    "clientEndDate": "2018-07-26",
    "clientEndTime": 1330,
    "clientReminderHours": 0,
    "clientStartDate": "2018-07-26",
    "clientStartTime": 1200,
    "coordinatorStaff": {Staff object for coordinator staff of appointment-see staff API page},
    "duration": 90,
    "endDate": "2018-07-26",
    "endTime": 1325,
    "fields": {Scheduler fields object for fields of fields of appointment-see scheduler fields API page},
    "invalidDates": false,
    "location": {Location object for location of appointment-see locations API page},
    "locationGroup": {Location group object for location group of appointment-see groups API page},
    "note": "",
    "price": 8,
    "reason": {Reason object for service of appointment-see services API page},
    "reasonGroup": {Reason group object for reason group of appointment-see groups API page},
    "remindClientSmsHours": 1,
    "remindStaffSmsHours": 0,
    "resource": {Resource object for resource of appointment-see resources API page},
    "resourceId": 2556,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment-see staff API page},
    "staffReminderHours": 0,
    "startDate": "2018-07-26",
    "status": "OPEN"
}

Code Block

language	js
title	PUT /appointments/{appointmentId}
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Aug 2, 2018 at 8:00 AM FNT",
    "appointmentDateTimeStaff": "Thursday, Aug 2, 2018 at 8:00 AM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 16902080,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": "",
    "classScheduleId": null,
    "client": {Client object for client of appointment-see clients API page},
    "clientConfirmedDate": 1532371154462,
    "clientConfirmed": false,
    "clientEndDate": "2018-08-02",
    "clientEndTime": 900,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-08-02",
    "clientStartTime": 800,
    "color": "#668CD9",
    "completedReason": null,
    "coordinatorStaff": null,
    "coupon": null,
    "couponId": null,
    "createddate": "2018-06-21 14:45:52",
    "createduser": "JoeSchmo",
    "customFieldDesc": "",
    "date": "2018-08-02",
    "dateCheckedIn": null,
    "dateCompleted": null,
    "discount": null,
    "endDate": "2018-08-02",
    "endTime": 930,
    "fields": {Scheduler fields object for fields of fields of appointment-see scheduler fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment-see locations API page},
    "locationGroup": {Location group object for location group of appointment-see groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment-see services API page},
    "reasonGroup": {Reason group object for reason group of appointment-see groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 2,
    "remindStaffSmsHours": 4,
    "resource": {Resource object for resource of appointment-see resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment-see staff API page},
    "staffReminderHours": 3,
    "staffRescheduleCount": 9,
    "startDate": "2018-08-02",
    "startTime": 945,
    "status": "OPEN",
    "subStatus": "CONFIRMED",
    "transactionFee": null,
    "waitlistId": null
}

Code Block

language	js
title	PUT /appointments/{appointmentId}/noshow
linenumbers	true
collapse	true

{
    "additionalStaffIdList": null,
    "address": null,
    "appointmentDateTimeClient": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "appointmentDateTimeStaff": "Thursday, Jul 26, 2018 at 12:00 PM FNT",
    "blockStaffIdList": [],
    "blockedStaffList": [],
    "businessId": 43111,
    "calendarId": 1726703,
    "cancelReason": null,
    "cancelUser": null,
    "changeReason": "",
    "classScheduleId": null,
    "client": {Client object for client of appointment-see clients API page},
    "clientConfirmedDate": 1532478709843,
    "clientConfirmed": false,
    "clientEndDate": "2018-07-26",
    "clientEndTime": 1330,
    "clientReminderHours": 0,
    "clientRescheduleCount": 0,
    "clientStartDate": "2018-07-26",
    "clientStartTime": 1200,
    "color": null,
    "completedReason": "",
    "coordinatorStaff": {Staff object for coordinator staff of appointment-see staff API page},
    "coupon": null,
    "couponId": null,
    "createddate": "2018-07-24 16:10:52",
    "createduser": "JoeSchmo",
    "customFieldDesc": "",
    "date": "2018-07-26",
    "dateCheckedIn": 1532525743459,
    "dateCompleted": 1532526150687,
    "dateStarted": 1532525579100,
    "discount": null,
    "endDate": "2018-07-26",
    "endTime": 930,
    "fields": {Scheduler fields object for fields of fields of appointment-see scheduler fields API page},
    "invitationUUId": null,
    "jobRequisitionId": null,
    "location": {Location object for location of appointment-see locations API page},
    "locationGroup": {Location group object for location group of appointment-see groups API page},
    "locationSuperGroup": null,
    "modifieddate": null,
    "modifieduser": null,
    "noPrefSelected": null,
    "noShowReason": null,
    "note": "",
    "packageSoldId": null,
    "price": null,
    "reason": {Reason object for service of appointment-see services API page},
    "reasonGroup": {Reason group object for reason group of appointment-see groups API page},
    "recall": null,
    "recallDate": null,
    "recallStatus": null,
    "recurringAppointmentId": 101096,
    "remindClientSmsHrs": 2,
    "remindStaffSmsHours": 4,
    "resource": {Resource object for resource of appointment-see resources API page},
    "seats": 1,
    "sendConfirmationToClient": false,
    "sendConfirmationToStaff": false,
    "staff": {Staff object for staff of appointment-see staff API page},
    "staffReminderHours": 3,
    "staffRescheduleCount": 9,
    "startDate": "2018-08-02",
    "startTime": 945,
    "status": "OPEN",
    "subStatus": "CONFIRMED",
    "transactionFee": null,
    "waitlistId": null
}

Property nameTypeDescriptionadditionalStaffIdListarrayDisplays staffIds for any additional staff members you add to the appointment so they cannot otherwise be booked for this time slot. appointmentDateTimeClientstringDisplays the date and time of the appointment as the client sees them.addressstringDisplays the address entered during appointment creation f appointment is set to a location of locationType VARIABLE.appointmentDateTimeStaffstringDisplays the date and time of the 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.blockStaffIdListarrayDisplays staffIds for any additional staff members you have added 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.blockedStaffListarrayDisplays full staff objects for any additional staff members you have added in the blockStaffIdList or additionalStaffIdList.businessIdintegerProvides unique numerical ID for the business that offers specified appointment. (Required)calendarIdintegerProvides unique numerical ID of specified appointment. (Required)cancelReasonstringDisplays any reason given for cancelling specified appointment.cancelUserstringDisplays as username of staff who cancelled specified appointment or as "WebClient" if client cancelled their own appointment. If appointment is marked as COMPLETED, username of the staff person who marked the appointment as completed displays here.changeReasonstringDisplays any reason given for changing specified appointment.classScheduleIdintegerIf specified appointment is an instance of a class schedule, this field will contain the unique numerical ID for that class schedule.clientobjectDisplays the object of client who is connected to specified appointment.clientConfirmDateintegerDisplays the date in milliseconds elapsed since January 1 1970 UTC format that client was marked as confirmed for appointment.clientConfirmedbooleanFlag for whether or not the client has confirmed the appointment. This can be done by checking the checkbox on the appointment profile, marking the status as confirmed, or the client clicking the confirm button on the reminder email.clientEndDatestringDisplays as date specified appointment is set to end without buffer displayed as YYYY-MM-DD.clientEndTimeintegerDisplays as time specified appointment is set to end without buffer displayed in military format.clientReminderHoursintegerDisplays the number of hours before the appointment that an email reminder will be sent to the client.clientRescheduleCountintegerDisplays the number of times client has rescheduled specified appointment.clientStartDatestringDisplays as date specified appointment is set to begin without buffer displayed as YYYY-MM-DD.clientStartTimeintegerDisplays as time specified appointment is set to begin without buffer displayed in military format.colorstringDisplays any color chosen to override specified appointment on the backoffice calendar.completedReasonstringDisplays any note the staff may have entered while marking the appointment as completed. Can be injected into completed email template sent to client with tag %COMPLETED_NOTE%.coordinatorStaffobjectDisplays staff object for the staff member that was the coordinator staff for this appointment. The coordinator staff's schedule is not blocked.couponobjectIf client enters a coupon while booking through the scheduler, the object of the coupon they entered will display here.couponIdintegerProvides unique numeric ID that is stored on the coupon object.createddatestringDisplays as date specified appointment was created in milliseconds elapsed since January 1, 1970 00:00:00 UTC form. (Required)createduserstringDisplays as username of the user who created specified appointment. If client booked appointment from scheduler would display as "WebClient". (Required)customFieldDescstringDisplays 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%. datestringProvides string representation of the date 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. (Required)dateCheckedInintegerDisplays as date the client checked in to specified appointment.dateCompletedintegerDisplays as date specified appointment was completed.dateStartedintegerDisplays as date specified appointment was marked as substatus of INPROGRESS.discountintegerIf coupon was applied, this displays as the total dollar value that was taken off the price of the service/class booked for.endDatestringProvides the date that specified appointment ends with buffer time alloted displayed as YYYY-MM-DD. (Required)endTimeintegerProvides the end time of the appointment accounting for any buffer on the reason displayed in military format. (Required)fieldsarrayDisplays an array of any custom field objects that were assigned to the appointment. For more information, please see the schedulerFieldList API page.invitationUUIdstringIf 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 appointmentjobRequisitionIdintegerProvides unique numeric ID of specified appointment's job requisition number.locationobjectDisplays the location object assigned to specified appointment. (Required)locationGroupobjectIf you assign the appointment to a specific location group, then this would be the object of that location group.locationSuperGroupobjectIf you assign the location group of specified appointment to a specific location super group, then this would be the object of that location super group.modifieddateintegerDisplays as date specified appointment was last modified in milliseconds elapsed since January 1, 1970 00:00:00 UTC form.modifieduserstringDisplays as username of user who last modified specified appointment. If client was last to modify then it would be displayed as "WebClient".noPrefSelectedbooleanDisplays if no preference has been selected for specified appointment.noShowReasonstringDisplays as reason given for a no show.notestringDisplays as note added to appointment profile in default comments field.packageSoldIdintegerDisplays as unique numerical ID of package used to redeem appointment against.pricestringDisplays as price set for specified appointment after adjusting for any coupons that may have been used.reasonobjectDisplays the reason object connected to specified appointment.reasonGroupobjectIf you assign the reason of specified appointment to a specific reason group, then this would be the object of that reason group.recallobjectIf a recall campaign has been set up that impacts this appointment, then the object of the recall campaign that the appointment is a part of shows here.recallDateintegerDisplays as goal date for 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.recallStatusstringDisplays as status of recall of specified appointment if applicable.recurringAppointmentIdintegerIf appointment is part of a repeating appointment series, then this provides unique numerical ID of repeating appointment series.remindClientSmsHoursintegerDisplays the number of hours before the appointment that an SMS reminder will be sent to the client.remindStaffSmsHoursintegerDisplays the number of hours before the appointment that an SMS reminder will be sent to the staff.resourceobjectDisplays any resource object connected to specified appointment.seatsintegerProvides number of seats for 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.sendConfirmationToClientbooleanFlag for whether or not a confirmation email should be sent to client on appointment POST/PUT. If set to TRUE then when appointment is created the confirmation will send out and when appointment is update the appointment changed email will send.sendConfirmationToStaffbooleanFlag for whether or not a confirmation/update email should be sent to staff on appointment POST/PUT. If set to TRUE then when appointment is created the confirmation will send out and when appointment is update the appointment changed email will send outstaffobjectDisplays the staff object for staff member connected to specified appointment. (Required)staffReminderHoursintegerDisplays the number of hours before the appointment that an email reminder will be sent to the staff.staffRescheduleCountintegerDisplays the number of times staf has rescheduled specified appointment.startDatestringProvides the date specified appointment starts with buffer displayed as YYYY-MM-DD. (Required)startTimeintegerDisplays the time specified appointment starts displayed in military format. (Required)statusstringDisplays the status of specified appointment. Possible values include PENDING, OPEN, NO_SHOW, COMPLETED, CANCELLED, DELETED.subStatusstringDisplays the substatus of 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,transactionFeestringDisplays as fee added to transaction added for specified appointment.waitListIdintegerIf 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 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

RequiredTypeDetailsbusinessIdtruenumberThis is generally your API keylocationtrueobjectMust include at least the locationId as part of the object passedlocationGroupfalseobjectMust include at least the groupId as part of the object passedstafftrueobjectMust include at least the professionalId as part of the object passedreasontrueobjectMust include at least the reasonId as part of the object passedreasonGroupfalseobjectMust include at least the groupId as part of the object passedclientfalseobjectMust include at least the clientId as part of the object passedfieldsfalsearray 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

clientStartDatetruestringThis is the start date of the appointment for the client. Should be formatted as YYYY-MM-DDclientEndDatetruestringThis 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 also be formatted as YYYY-MM-DDstartDatetruestringThis 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-31endDatetruestringThis 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-01clientStartTimetruenumber

This is the start time of the appointment for the client. Should have military time format

Formatting examples:

an appointment that starts at 12:15am should be passed as 15
an appointment that starts at 11:30am should be passed as 1130
an appointment that starts at 2:45pm should be passed as 1445 and so on

clientEndTimetruenumberThis 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 in the same way the cilentStartTime is abovestartTimetruenumber

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

endTimetruenumber

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.

classScheduleIdtrue (if selected reason is of reasonType class)numberIf 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 their could be multiple sessions scheduled for the same date and time at the same location with the same staff for the same reason.clientReminderHourstruenumber

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

If you want the email to go out 12 hours before the start time of the appointment, set the value to 12
If you want the email to go out 1 day before the start time of the appointment, set the value to 24 (1 day = 24 hours)
If you want the email to go out 1.5 days before the start time of the appointment, set the value to 36

staffReminderHourstruenumberThis 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 clientReminderHoursremindClientSmsHrstruenumberThis 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 clientReminderHoursremindStaffSmsHrstruenumberThis 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 clientReminderHourssendConfirmationToClienttruebooleanIf 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.sendConfirmationToStafftruebooleanIf you want the New Appointment email to send out to the staff upon saving the appointment, set this to true. Otherwise set it to falsestatustruestring

Accepted values:

OPEN
PENDING_CONFIRMATION (if need to get staff confirmation that they can take the appointment before it is set to OPEN)

pendingConfirmationfalsebooleanIf going through the pending confirmation process for an appointment, set this value to true. Otherwise, no need to passresourcefalseobject

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).

packageSoldIdfalsenumberSet to value of selected package that you would like to use for the appointment

modifiedUser": "JoeSchmo",
    "reason": {Reason object for reason of time off - for more info, see Services API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff with time off - for more info, see Staff API page},
    "startDate": "2018-10-01",
    "startTime": 1100,
    "status": "Open",
    "timeOffId": 17360947
}

Code Block

language	js
title	POST /timeOffBulk
linenumbers	true
collapse	true

[{
    "businessId": 43111,
    "changeReason": null,
    "color": null,
    "createdDate": "2018-08-03 21:39:38",
    "createdUser": "JoeSchmo",
    "description": "Need an even longer break!",
    "endDate": "2018-10-01",
    "endTime": "1400",
    "modifiedDate": "2018-08-07 11:34:56",
    "modifiedUser": "JoeSchmo",
    "originalStartDate": "2018-10-01",
    "reason": {Reason object for reason of time off - for more info, see Services API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff with time off - for more info, see Staff API page},
    "staffId": 80891,
    "startDate": "2018-10-01",
    "startTime": "1100",
    "status": "1100",
    "timeOffId": 17360947
}}]

Code Block

language	js
title	PUT /timeOff/{timeOffId}
linenumbers	true
collapse	true

{
    "businessId": 43111,
    "changeReason": null,
    "color": null,
    "createdDate": "2018-08-03 14:39:38",
    "createdUser": "JoeSchmo",
    "description": "Need a longer break!",
    "endDate": "2018-10-01",
    "endTime": "1400",
    "modifiedDate": "2018-08-07 11:34:56",
    "modifiedUser": "JoeSchmo",
    "reason": {Reason object for reason of time off - for more info, see Services API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff with time off - for more info, see Staff API page},
    "staffId": 80891,
    "startDate": "2018-10-01",
    "startTime": "1100",
    "status": "1100",
    "timeOffId": 17360947
}

For the appointments report endpoint, please refer to the Appointments API page.

Property name	Type	Required	Writable	Description
businessId	integer	Yes		Provides unique numeric ID of the business offering specified time off.
changeReason	boolean			Indicates whether or not the reason of the specified time off has been changed.
color	string		Yes	Displays any color chosen to override specified time off on the backoffice calendar.
createdDate	string			Displays as date specified time off was created as YYYY-MM-DD with time after.
createdUser	string			Displays the username of user who created specified time off.
description	string		Yes	Displays any description that was added to time off profile.
endDate	string	Yes	Yes	Provides the date that specified time off is set to end as YYYY-MM-DD.
endTime	integer	Yes	Yes	Provides the time that specified time off ends displayed in military format.
modifiedDate	string			Displays as date specified time off was last modified as YYYY-MM-DD with time after.
modifiedUser	string			Displays the username of user who last modified specified time off.
reason	object	Yes	Yes	Displays the reason object connected to specified time off - for more info, see Services API page.
recurringAppointmentId	integer			If specified time off is part of a repeating time off series, then this provides unique numeric ID of that series.
staff	object	Yes	Yes	Displays the staff object connected to specified time off - for more info, see Staff API page.
startDate	string	Yes	Yes	Provides the date that specified time off is set to begin as YYYY-MM-DD.
startTime	integer	Yes	Yes	Provides the time that specified time off is set to begin displayed in military format.
status	string	Yes	Yes	Displays the status of time off. Possible values include Open, Closed, or Cancelled.
timeOffId	integer	Yes, on PUT calls		Provides unique numeric ID of specified time off.

Version	Old Version 1	New Version Current
Changes made by	Joel Morgan Kearney (Unlicensed)	Joel Kearney
Saved on	Aug 03, 2018	Sept 01, 2023

Versions Compared

Key

Time Off API Endpoints

Time Off API Responses

Time Off Parameters

Time Off API Parameters

How to Get List of Time Offs

Time Off API Request Body/Payloads

Time Off API Responses

Time Off Object Values

Guide for Adding New Appointments

Time Off Object Values