Page Comparison

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, 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 account API, as 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

Returns an array of appointments with specified status.

GET /timeOff/{timeOffId}Returns a JSON object for specified time off period.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 BlocklanguagejstitleGET

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 object timeOff object. 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 /appointmentstimeOff/{appointmentIdtimeOffId}	Updates an existing appointmenttime off object. Request body/payload: Must pass an appointment a timeOff object with the desired changes made.
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. Request body/payload: Must pass an appointment 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.

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,
    "clientEndTime": "1400",
    "clientStartTime": "1100",
    "color": null,
    "createdDate": "2019-02-11 17:27:08",
    "createdUser": "JoeSchmo",
    "description": "Babysitter got sick",
    "endDate": "2019-02-13",
    "endTime": "1400",
    "modifiedDate": "2019-02-11 17:27:08",
    "modifiedUser": "JoeSchmo",
    "note": "Babysitter got sick",
    "reason": {Reason object for reason of time off - for more info, see Services API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff of time off - for more info, see Staff API page},
    "staffId": 80891,
    "startDate": "2019-02-13",
    "startTime": "1300",
    "status": "OPEN",
    "timeOffId": 20050788
}

Code Block

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

{
    "businessId": 43111,
    "changeReason": null,
    "color": null,
    "createdDate": "2018-08-03 14:39:38",
    "createdUser": "JoeSchmo",
    "description": "Need a break!",
    "endDate": "2018-10-01",
    "endTime": 1200,
    "modifiedDate": "2018-08-07 15:10:27",
    "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": 1200"1400",
    "modifiedDate": "2018-08-07 1511:1034:2756",
    "modifiedUser": "JoeSchmo",
    "reason": {Reason object for reason of time off - for more info, see servicesServices API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff with time off - for more info, see staffStaff API page},
    "staffId": 80891,
    "startDate": "2018-10-01",
    "startTime": "1100",
    "status": "Open1100",
    "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 availability. (Required)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. (Required)
createdUser	string			Displays the username of user who created specified time off. (Required)
description	string		Yes	Displays any description that was added to time off profile.
endDate	string	Displays Yes	Yes	Provides the date that specified time off is set to end as YYYY-MM-DD.
endTime	integerDisplays as military	Yes	Yes	Provides the time that specified session endstime off ends displayed in military format. (Required)
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 appointment time off series, then this provides unique numeric ID of that repeating appointment series.
staff	object	Yes	Yes	Displays the staff object connected to specified time off - for more info, see Staff API page.
startDate	string	Displays Yes	Yes	Provides the date that specified time off is set to begin as YYYY-MM-DD.
startTime	integerDisplays as military	Yes	Yes	Provides the time that specified session time off is set to begin displayed in military format. (Required)
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 5	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