Working Hours
- Joel Morgan Kearney (Unlicensed)
- Joel Kearney
These are the endpoints that are available under the /workingHours path, which shows hours of service availability that both your staff and locations have.
Endpoint | Description |
|---|---|
GET /workingHours/location/{locationId} | Returns a workingHours object with the business ID and period array for the location the call was made on behalf of. |
| GET /workingHours/staff/{professionalId} | Returns a workingHours object with the business ID and period array for the staff the call was made on behalf of. |
POST /workingHours/save/location/{locationId} | Used when creating a new timeslot of availability for a staff person at the location indicated by the call in an existing period. Even if you are just adding a day to an existing date range but the rest of the timeslots already exist, you would want to use this POST call to create the new day and timeslots on that day. preview and splitDate parameters are used with this call. Request body/payload: Pass a period object with the startDate and endDate defined, and the objects array on the period object with the days array on it and on the objects within the days array with timeslots defined on it. For these calls, you need to pass a workingHours object with all required fields and any fields you want to set filled in the body of the payload. We have an example of the workingHours object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
| POST /workingHours/save/staff/{professionalId} | Used when creating a new time slot of availability at a location for the staff person indicated by the call in an existing period. Even if you are adding a day to an existing date range, but the rest of the time slots already exist, you would want to use this POST call to create the new day and time slots on that day. Request body/payload: Pass a workingHours period object with the startDate and endDate defined, and the objects array on the period object with the days array, and on the objects within the days array with the times defined on them. For these calls, you need to pass a workingHours 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 workingHours object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
| POST /workingHours/fillTimeSlots/staff/{professionalIdList} | Returns a workingHours period object so a user can edit times on the days that were selected. This call is made between steps 2 and 3 on the Add Staff Availability flow under Settings > Time. Request body/payload: Pass an objects array with a days array with the days you want with the "checked" property set to true/false depending on whether or not you want to add time slots for that day. If adding hours for multiple staff members at one location, you would pass the professionalIdList as a comma-separated list. So for example, if the staff you want to add hours for have staff IDs of 12345 and 67890, then you would want to make the call as POST /workingHours/fillTimeSlots/staff/12345,67890. |
| POST /workingHours/update | Updates existing time slots or date ranges. The originalStartDate and originalEndDate parameters are used with this call. Request body/payload: Pass a workingHours period object with the update you want defined in the proper property of the object. I.e. if you are updating the end date of the period, pass the period object with the endDate updated; if you are updating the end time of a specific time slot, pass the period with the endTime property of the time slot (nested under period object > objects > days > times) set to the desired new value. For these calls, you need to pass a workingHours 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 workingHours object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
| POST /workingHours/delete | Removes whatever time slots you pass in the period object > objects array > days array > times array so that those times are no longer available for booking. Request body/payload: Pass a workingHours period object with the startDate and endDate defined, and an objects array on the period object with a days array on it and on the objects within the days array with only the times defined on it that you want to remove. If you want to keep a time the same, set the times array on the day object to just an empty array [ ]. |
| PUT /workingHoursList | Creates a new period object for a location/staff person. Request body/payload: Pass a workingHours period object with all required fields defined. For these calls, you need to pass a workingHours object with all required fields and any fields you want to set filled in the body of the payload. We have an example of the workingHours object in the responses section below and have indicated the required fields in the object values table at the bottom of this page. |
| DELETE /workingHours/deleteAll | Deletes all availability from either a staff or location profile. |
Data points passed on in the request URL portion of the API call that are used to filter the data that is being requested.
Parameter | Type | Endpoints to be used with | Description |
|---|---|---|---|
| preview | boolean | POST /workingHours | If set to true, the working hours period will not save to the database but just reformat to let you confirm before saving. |
| splitDate | string | POST /workingHours | Allows you to break an existing period date range into two based on what split date you pass so that you can edit the two new date ranges separately. Should be formatted as YYYY-MM-DD. |
| originalStartDate | string | POST /workingHours/update | If you update the startDate of the period the database will be able to use this parameter to reference back which period needs to get updated. Should be formatted as YYYY-MM-DD. |
| originalEndDate | string | POST /workingHours/update | If you update the endDate of the period the database will be able to use this parameter to reference back which period needs to get updated. Should be formatted as YYYY-MM-DD. |
| startDate | string | GET /workingHours/location/{locationId} | If you submit a request to the endpoint with both the startDate and endDate parameters filled out, then only working hours taking place within those hours should return. Should be formatted as YYYY-MM-DD. |
| endDate | string | GET /workingHours/location/{locationId} | If you submit a request to the endpoint with both the startDate and endDate parameters filled out, then only working hours taking place within those hours should return. Should be formatted as YYYY-MM-DD. |
| keepPastDates | boolean | GET /workingHours/location/{locationId} | If set to true, then the API will not trim off working hours that occurred in the past. By default the endpoint assumes this is false. |
| staffIdList | integer array | DELETE /workingHours/deleteAll | Should be set as a comma-separated list of staffIds that you want to delete all availability of. |
| locationIdList | integer array | DELETE /workingHours/deleteAll | Should be set as a comma-separated list of locationIds that you want to delete all availability of. |
The objects below represent the minimum viable objects to pass that are needed to create or update a workingHours 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.
We have split the Object Values table into multiple smaller tables to reflect the different levels of arrays present in the workingHours API calls. For example, the first table shows what properties are present in the parent API call, but the "period" property is an array of objects. Inside this "period" array lie the properties found in the third table, and so on until you reach the "times" array in the second to last table. The properties that can be found in the "times" array are then listed in the last table.
Business-level array table:
| Property name | Type | Required | Description |
|---|---|---|---|
| businessId | integer | Yes | Provides unique numerical ID for your business. |
period | array | Yes | Provides info about the service availability for the location/staff for which the GET call was made. Definitions of properties within an object on this array are defined in the table labeled "Period-level array table" below. |
Period-level array table:
| Property name | Type | Required | Writable | Description |
|---|---|---|---|---|
| endDate | string | Yes | Provides the date specified staff person/location's service availability ends, in YYYY-MM-DD format - if set to null then availability extends indefinitely. | |
| endDateDate | integer | Yes | The endDate formatted as milliseconds since Unix Epoch (1/1/1970). | |
| firstWeek | boolean | If set to true, that means that the repeatSchedule property would need to be set to "Month" and the user wants the schedule to repeat on the first instance of the day that is selected per month. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| fourthWeek | boolean | If set to true, that means that the repeatSchedule property would need to be set to "Month" and the user wants the schedule to repeat on the fourth instance of the day that is selected per month. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| fri | boolean | Only set on the initial POST to create a preview of the schedule. After that, the days of the week contained in the objects array are used to define the schedule - if the "fri" property is set to true then the repeating schedule would repeat on Fridays. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| lastWeek | boolean | If set to true, that means that the repeatSchedule property would need to be set to "Month" and the user wants the schedule to repeat on the last instance of the day that is selected per month (for instances when there are 5 instances of a day in a month, not just 4). Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| mon | boolean | Only set on the initial POST to create a preview of the schedule. After that, the days of the week contained in the objects array are used to define the schedule - if the "mon" property is set to TRUE then the repeating schedule would repeat on Mondays. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| objects | array | Yes | Displays an array of all objects that offer working hours of service availability. Definitions of properties within an object on this array are defined in the table labeled "Objects-level array table" below. | |
| recurring | boolean | Yes | If set to true, then all other boolean-type on this level will be used to determine the returned period objects after the call is made to POST workingHours/save/staff/26982?resume=0&preview=true&splitDate=undefined. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | |
| repeatInterval | integer | Set to a value for which the repeatSchedule property applies. For instance, if repeatSchedule is set to "Week" and repeatInterval is set to 2, then the schedule would return repeating every 2 weeks. Only applies when recurring property is set to true. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| repeatSchedule | string | Can be set to either "Week" or "Month". Only applies when recurring property is set to true. If recurring is true, then it looks at the repeatSchedule property. If repeatSchedule is set to Month and repeatInterval is set to 2, then whatever recurring schedule has been defined by the yellow properties would repeat every 2 months on the week(s) that were set to true on the days of the week that were set to true. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| sat | boolean | Only set on the initial POST to create a preview of the schedule. After that, the days of the week contained in the objects array are used to define the schedule - if the "sat" property is set to true here then the repeating schedule would repeat on Saturdays. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| secondWeek | boolean | If set to true, that means that the repeatSchedule property would need to be set to "Month" and the user wants the schedule to repeat on the second instance of the day that is selected every month. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| startDate | string | Yes | Yes | Provides the date specified staff person or location's service availability begins, in YYYY-MM-DD format. |
| startDateDate | integer | Yes | Yes | The startDate formatted as milliseconds since Unix Epoch (1/1/1970). |
| sun | boolean | Only set on the initial POST to create a preview of the schedule. After that, the days of the week contained in the objects array are used to define the schedule - if the "sun" property is set to true here then the repeating schedule would repeat on Sundays. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| thirdWeek | boolean | If set to true, that means that the repeatSchedule property would need to be set to "Month" and the user wants the schedule to repeat on the third instance of the day that is selected per month. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| thu | boolean | Only set on the initial POST to create a preview of the schedule. After that, the days of the week contained in the objects array are used to define the schedule - if the "thu" property is set to true here then the repeating schedule would repeat on Thursdays. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| tue | boolean | Only set on the initial POST to create a preview of the schedule. After that, the days of the week contained in the objects array are used to define the schedule - if the "tue" property is set to true here then the repeating schedule would repeat on Tuesdays. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". | ||
| wed | boolean | Only set on the initial POST to create a preview of the schedule. After that, the days of the week contained in the objects array are used to define the schedule - if the "wed" property is set to true here then the repeating schedule would repeat on Wednesdays. Only used in the initial creation of working hours under Settings > Time > Add Staff Availability if you choose the schedule type "Schedule that repeats every 2 weeks or more". |
Objects-level array table:
| Property name | Type | Required | Description |
|---|---|---|---|
| days | array | Yes | An array of up to 7 objects representing the individual days of the week, this determines which days the staff and location on this level are available for booking. On the initial POST calls to create working hours, would send all 7 with the checked property on each day set to true/false depending on whether or not the staff/location is available on that day. On the GET call, only days that have hours available return so the "checked" property on the day is no longer needed. Definitions of properties within an object on this array are defined in the table labeled "Days-level array table" below. |
| locationId | integer | Yes | Provides unique ID of the location where the staff person listed via the professionalId and professionalName properties is available during this date range for the days selected in the days array. |
| locationName | string | Yes | Displays as the name of the location where the staff person listed via the professionalId and professionalName properties is available during this date range for the days selected in the days array. |
| objectType | string | Yes | Displays as the type of object that the specified working hours belong to. Possible values include "PROFESSIONAL". |
| professionalId | integer | Yes | Provides unique numerical ID of the staff members that are available during the days selected in the days array at the location listed via the locationId and locationName properties. |
| professionalName | string | Yes | Displays as the name of staff members that are available during the days selected in the days array at the location listed via the locationId and locationName properties. |
Days-level array table:
| Property name | Type | Required | Description |
|---|---|---|---|
| checked | boolean | Yes | Needed for initial POST workingHours/fillTimeSlots/staff/{professionalIdList} call to get hours to fill in. On the GET call, only days which have hours return, so it can be assumed that if a day returns then there are hours/times available on it. |
| times | array | Yes | This is an array of objects representing the timeslots that the staff or location has available on the given day between the period's start and end dates. Definitions of properties within an object on this array are defined in the table labeled "Times-level array table" below. |
| workday | integer | Yes | Displays as numerical property representing the day of the week. (Sunday = 0, Monday = 1, ..., Saturday = 6). |
Times-level array table:
| Property name | Type | Required | Writable | Description |
|---|---|---|---|---|
| active | boolean | Yes | If you want to keep the time in the array, then you would set this to true. In the DELETE method call for the workingHours endpoint, you would want to set the active property value to false on any timeslots that you don't want to keep. | |
| endTime | integer | Yes | Yes | This value represents the time of day that the working hours close out. It should be inputted in military format (i.e. 1:00pm should be sent as 1300), and represents the end time of the last possible appointment a client could book for this timeslot. |
| endTimeObj | string | Yes | Provides string value representation of the end time. Can be used for display purposes if needed. | |
| roomNumber | integer | Yes | Provides the room number that the specified working hours are set for. | |
| startTime | integer | Yes | Yes | This value is the time of day that the working hours open up. It should be inputted in military format (i.e. 1:00pm should be sent as 1300), and represents the start time of the first possible appointment a client could book for this timeslot. |
| startTimeObj | string | Yes | Provides string value representation of the start time. Can be used for display purposes if needed. | |
| workScheduleId | integer | Yes, on POST update calls | Provides unique numerical ID of a particular timeslot in period object. |