Time Off

The Time Off API is used to access, create, and modify the periods of time off taken on your business' account. The Time Off API is connected to the Staff 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.



On this page




Time Off API Endpoints

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.

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 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 /timeOff/{timeOffId}

Updates an existing time off object.

Request body/payload: Must pass a timeOff object 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 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.




Time Off API Parameters

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:
  1. You set the parameter onlyTimeOff to 1
  2. The parameter excludeTimeOff is set to false
  3. the serviceIdList parameter is either sent in as null or only includes ids for reasons that are of reasonType PERSONAL




Time Off API Request Body/Payloads


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.

POST /timeOffBulk
{
    "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": [80891],
    "startDate": "2019-02-13",
    "startTime": "1300"
}
PUT /timeOff/{timeOffId}
{
    "businessId": 43111,
    "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
}




Time Off API Responses

GET /timeOff/{timeOffId}
{
    "businessId": 43111,
    "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-see services API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff with time off-see staff API page},
    "startDate": "2018-10-01",
    "startTime": 1100,
    "status": "Open",
    "timeOffId": 17360947
}
POST /timeOffBulk
[{
    "allDay": true,
    "businessId": 43111,
    "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-see services API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff with time off-see staff API page},
    "staffId": 80891,
    "startDate": "2018-10-01",
    "startTime": "1100",
    "status": "1100",
    "timeOffId": 17360947
}}]
PUT /timeOff/{timeOffId}
{
    "allDay": true,
    "businessId": 43111,
    "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",
    "originalStartDate": "2018-10-01",
    "reason": {Reason object for reason of time off-see services API page},
    "recurringAppointmentId": null,
    "staff": {Staff object for staff with time off-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.




Time Off Object Values

Property nameTypeRequiredWritableDescription
businessIdintegerYes
Provides unique numeric ID of the business offering specified time off.
colorstring
YesDisplays any color chosen to override specified time off on the backoffice calendar.
createdDatestring

Displays as date specified time off was created as YYYY-MM-DD with time after. 

createdUserstring

Displays the username of user who created specified time off. 
descriptionstring
YesDisplays any description that was added to time off profile.
endDatestringYesYesProvides the date that specified time off is set to end as YYYY-MM-DD. 
endTimeintegerYesYesProvides the time that specified time off ends displayed in military format. 
modifiedDatestring

Displays as date specified time off was last modified as YYYY-MM-DD with time after.
modifiedUserstring

Displays the username of user who last modified specified time off.
reasonobjectYesYesDisplays the reason object connected to specified time off - for more info, see Services API page. 
recurringAppointmentIdinteger

If specified time off is part of a repeating time off series, then this provides unique numeric ID of that series.
staffobjectYesYesDisplays the staff object connected to specified time off - for more info, see Staff API page.
startDatestringYesYesProvides the date that specified time off is set to begin as YYYY-MM-DD.
startTimeintegerYesYesProvides the time that specified time off is set to begin displayed in military format. 
statusstringYesYesDisplays the status of time off. Possible values include Open, Closed, or Cancelled. 
timeOffIdintegerYes, on PUT calls
Provides unique numeric ID of specified time off.