Shift Plans
For more information about the concept of Shift Plans in Deputy click here. Please note that this API is in BETA and this page should be checked regularly for any updates.
Retrieving shifts that contain shift plans
In Deputy, Shift Plans are handled via the concept of child shifts within the shift API response object. To retrieve shifts which contain shift plans, you will need to use the v2 Shifts Deputy API.
At the current time the v2 shifts API can only retrieve shifts for individual employees by using their record id number in the URL. By default the v2 Shifts API looks at the previous 7 days so if you do not set a timestamp in the request, you will retrieve any shifts related to the employee for the past 7 days.
Getting the rosters/shifts for the past 7 days
To retrieve shifts for the past 7 days by default the following API request is needed
URL
curl --request GET 'https://{install}.{geo}.deputy.com/api/v2/management/shifts?published=TRUE&employee={employeerecordid}
This will by default return the last 7 days of shifts assigned to that employee from the time the API request is made.
To retrieve shifts for a specific time frame including in the future use the following API request
URL
curl --request GET 'https://{install}.{geo}.deputy.com/api/v2/management/shifts?published=TRUE&employee={employeeid}&start=YYYY-MM-DDTHH:MM:SS{timezone offset}HH:MM&end=YYYY-MM-DDTHH:MM:SS{timezone offset}}HH:MM
As can be seen the URL structure demands a start time and end time for this scenario as well as a timezone offset. As an example, lets retrieve all shifts for June 2024 for an employee with the record id 587 where the timezone should be Sydney, Australia (GMT +11)
The structure of the url call would be
https://{install}.{geo}.deputy.com/api/v2/management/shifts?published=TRUE&employee=587&start=2024-06-01T00:00:00%2B11:00&end=2024-06-30T23:59:59%2B11:00
The employee id is set to 587 and to account for the timezone offset we have included %2B
for the code for +. So +11 which is the GMT offset for Sydney, Australia.
Sample Response
The response will be the same structure no matter whether shift plans exists in the shift or not. This is defined by the children
array in the Shift object response.
{
"success": true,
"data": [
{
"id": 1170,
"start": "2024-06-14T09:00:00+10:00",
"end": "2024-06-14T17:00:00+10:00",
"mealbreakDuration": 0.5,
"mealbreakSlots": [
{
"slotType": "BREAK",
"start": 0,
"end": 1800,
"state": "DURATION_ONLY",
"canStartEarly": true,
"canEndEarly": true,
"isMandatory": true,
"type": "MEAL_BREAK",
"typeLabel": "Meal Break"
}
],
"duration": 7.5,
"cost": 0,
"area": 48,
"employee": 587,
"note": "",
"warning": "is not set as preferred to work in [300G] Area1",
"warningOverrideComment": "Override by Simon Hutchinson on Fri 14/06/24 11:40 AM",
"isPublished": true,
"timesheet": 0,
"isOpen": false,
"approvalRequired": false,
"confirmationStatus": "ROSTER_CONFIRMATION_NOT_REQUIRED",
"confirmationNote": "",
"confirmedByWhom": 0,
"confirmedAt": "",
"swapStatus": "SWAP_STATUS_NOT_REQUIRED",
"swapApprovedBy": 0,
"shiftTemplate": 1,
"children": [
{
"id": 1171,
"start": "2024-06-14T09:00:00+10:00",
"end": "2024-06-14T13:00:00+10:00",
"cost": 0,
"area": 48,
"canEdit": true,
"parentId": 1170,
"isOpen": false,
"approvalRequired": false,
"isPublished": true,
"confirmationStatus": "ROSTER_CONFIRMATION_NOT_REQUIRED",
"confirmedByWhom": 0,
"confirmedAt": "",
"creator": 1,
"createdAt": "2024-06-14T11:40:22+10:00",
"modifiedAt": "2024-06-14T11:40:36+10:00"
},
{
"id": 1172,
"start": "2024-06-14T13:00:00+10:00",
"end": "2024-06-14T15:00:00+10:00",
"cost": 0,
"area": 73,
"canEdit": true,
"parentId": 1170,
"isOpen": false,
"approvalRequired": false,
"isPublished": true,
"confirmationStatus": "ROSTER_CONFIRMATION_NOT_REQUIRED",
"confirmedByWhom": 0,
"confirmedAt": "",
"creator": 1,
"createdAt": "2024-06-14T11:40:22+10:00",
"modifiedAt": "2024-06-14T11:40:36+10:00"
},
{
"id": 1173,
"start": "2024-06-14T15:00:00+10:00",
"end": "2024-06-14T17:00:00+10:00",
"cost": 0,
"area": 74,
"canEdit": true,
"parentId": 1170,
"isOpen": false,
"approvalRequired": false,
"isPublished": true,
"confirmationStatus": "ROSTER_CONFIRMATION_NOT_REQUIRED",
"confirmedByWhom": 0,
"confirmedAt": "",
"creator": 1,
"createdAt": "2024-06-14T11:40:22+10:00",
"modifiedAt": "2024-06-14T11:40:36+10:00"
}
],
"canEdit": true,
"customFields": [],
"customFieldData": 0,
"creator": 1,
"createdAt": "2024-06-14T11:40:02+10:00",
"modifiedAt": "2024-06-14T11:40:36+10:00",
"consentChangesets": []
}
],
"nextCursor": "1"
}
In this response there is three entries in the children
array meaning there is 3 shift plans which make up the entire shift. As can be seen the overall response is in an array, if an employee has more than 1 shift/shift plan which is within the defined time period, they will be returned as multiple objects inside the data array.
Data Element Info
Data Element | Info |
---|---|
success | Whether the data request was successful or not. If the data request is not successful, a different response will be returned defining what the problem was (for example not including an employee id when requesting this data) |
data | The array which contains the shift/shift plans objects which makes up the response |
id | The id record of the shift/shift plans |
start | The start time of the shift including timezone |
end | The end time of the shift including timezone |
mealbreakDuration | The length in hours (decimal) that breaks have been scheduled for the shift |
mealbreakSlots | Array containing information about meal breaks scheduled in the shift |
mealbreakSlots - slotType | The type of slot |
mealbreakSlots - start | The start time of the scheduled mealbreak in unix ticks after the start of the shift. If 0 this means the break has not been scheduled specifically |
mealbreakSlots - end | The end time of the scheduled mealbreak in unix ticks after the start of the shift. |
mealbreakSlots - state | This defines whether a specific mealbreak has been added to the shift or whether its only the duration which has been set and the employee can take break whenever |
mealbreakSlots- canStartEarly | Boolean true/false - Defines whether when a meal break has been specifically scheduled if the employee is allowed to start that break early |
mealbreakSlots- canEndEarly | Boolean true/false - Defines once the meal break has started whether an employee is allowed to clock back into the shift early |
mealbreakSlots - isMandatory | Boolean true/false - Defines whether the break must be taken as part of the shift. |
mealbreakSlots - type | The type of break |
mealbreakSlots - typeLabel | The label of the type of the break |
duration | The duration of the shift in hours decimal |
cost | The cost of the shift. This is only calculated once a timesheet generated from the shift is approved. |
area | The id record number of the area related to the shift |
employee | The id record number of the employee related to the shift |
note | Any note added to the shift by the manager |
warning | Any warning in text that the manager was presented before approving the shift for publish |
warningOverrideComment | Any comment related to why a shift warning was overriden by a manager. |
isPublished | Boolean true/false - whether the shift is published or draft |
timesheet | If a timesheet exists linked to the shift its record id will appear here |
isOpen | Whether the shift is open and no employee assigned yet |
approvalRequired | Whether an employee has to confirm the shift for it to be valid |
confirmationStatus | Text about the status of the shift confirmation |
confirmationNote | If an employee has confirmed a shift and added a note it will be added here |
confirmedByWhom | If an employee has confirmed a shift the record id for the employee will be added here |
confirmedAt | If an employee has confirmed a shift the timestamp of when the employee confirmed the shift |
swapStatus | Whether the shift is allowed to be swaped |
shiftTemplate | |
children | This array defines the shift plans on the shift if one exists. Each entry in the array is a sub-shift within the overall shift. |
children - id | The id record number of the sub-shift |
children - start | The start time including timezone of the sub-shift |
children - cost | The cost of the sub-shift. This will not be available until a timesheet related to the sub-shift is approved. |
children - area | The record id of the area the sub-shift is for |
children - employee | The record id of the employee the sub-shift is for |
children - note | Any note attached to the sub-shift |
children - warning | Any warning in text related to the sub-shift |
children - warningOverrideComment | Any comment in text as to why the warning was overridden |
children - isPublished | Boolean true/false. Whether the sub-shift is published |
children - timesheet | If there is a timesheet related to the sub-shift, the timesheet record id will appear here |
children - isOpen | Whether an employee is assigned to the sub-shift or not |
children - approvalRequired | Whether an employee has to confirm the shift |
children - confirmationStatus | Status of the shift in terms of confirmation if it has been required |
children - confirmationNote | If the employee when confirming the sub-shift has added a note it will appear here |
children - confirmedByWhom | The record id number of the employee who confirmed the sub-shift. 0 if not required |
children - confirmedAt | The time including timezone the shift was confirmed. Blank if not required or not confirmed |
children - swapStatus | The swap status of the sub-shift |
children- shiftTemplate | |
canEdit | Whether the shift can be edited |
customFields | Any custom fields related to the shift, primarily from our Enterprise product |
customFieldData | If custom fields exist on the response this will be 1 |
creator | The record id of the user who created the shift |
createdAt | The time including timezone as to when the shift was created |
modifiedAt | The time including timezone as to when the shift was last modified |
consentChangesets | Any changes related to consent and Fair Work Week that has been related to this shift. |
nextCursor | In a scenario where pagination is required due to the large data response, the cursor will tell you where the next request should begin to get the next page of data. |
Adding a shift with shift plans to Deputy
Adding a shift to Deputy including shift plans requires you to include the sub-shifts as part of the children array.
URL
curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v2/management/shifts
Sample Payload - One Location
{
"data": {
"shift": {
"area": 13,
"employee": 173,
"start": "2024-06-16T09:00:00+10:00",
"end": "2024-06-16T17:00:00+10:00",
"isOpen": false,
"mealbreakSlots": [
{
"slotType": "BREAK",
"state": 3,
"canStartEarly": true,
"canEndEarly": true,
"isMandatory": true,
"type": "MEAL_BREAK",
"start": 0,
"end": 900
},
{
"slotType": "BREAK",
"state": 3,
"canStartEarly": false,
"canEndEarly": false,
"isMandatory": true,
"type": "REST_BREAK",
"start": 900,
"end": 2700
}
],
"note": "shift notes",
"approvalRequired": false,
"children": [
{
"start": "2024-06-16T09:00:00+10:00",
"end": "2024-06-16T11:30:00+10:00",
"area": 13
},
{
"start": "2024-06-16T11:30:00+10:00",
"end": "2024-06-16T17:00:00+10:00",
"area": 15
}
],
"customFields": [],
},
"override": {
"shiftValidation": true,
"publishValidation": false
}
}
}
In this example we are adding a shift to one location and there is two sub-shifts. One beginning at 9am and finishing at 11:30am and another starting at 11:30am and finishing at 5pm in a different part of the business.
The response you will get once added, will reflect the same as if you had just retrieved the shift.
This would appear like so in the Deputy UI
![The Deputy UI showing the shift as well as the two sub-shifts from 9am-11:30am and 11:30am - 5pm](https://files.readme.io/bc76639-image.png)
The Deputy UI showing the shift as well as the two sub-shifts from 9am-11:30am and 11:30am - 5pm
Sample Payload - Shift between 9am and 5pm which has multiple locations for shift plans
{
"data": {
"shift": {
"area": 13,
"employee": 173,
"start": "2024-06-17T09:00:00+10:00",
"end": "2024-06-17T17:00:00+10:00",
"isOpen": false,
"mealbreakSlots": [
{
"slotType": "BREAK",
"state": 3,
"canStartEarly": true,
"canEndEarly": true,
"isMandatory": true,
"type": "MEAL_BREAK",
"start": 0,
"end": 900
}
],
"note": "",
"approvalRequired": false,
"children": [
{
"start": "2024-06-17T09:00:00+10:00",
"end": "2024-06-17T11:30:00+10:00",
"area": 13
},
{
"start": "2024-06-17T11:30:00+10:00",
"end": "2024-06-17T17:00:00+10:00",
"area": 62
}
],
"customFields": [],
},
"override": {
"shiftValidation": true,
"publishValidation": false
}
}
}
Although we are adding sub-shifts to different locations, this is still handled by the area id number. In this case area 13 is related to one location in the Deputy install and area 62 is related to another. A sample of how this would display in the Deputy UI is below.
![The Deputy UI showing two sub-shifts across multiple locations.](https://files.readme.io/d1dae76-image.png)
The Deputy UI showing two sub-shifts across multiple locations.
Updating an existing shift
It's possible to update an existing shift including those which have shift plans enabled within them. Follow this guide to do so.
URL
curl --request PUT --url 'https://{install}.{geo}.deputy.com/api/v2/management/shifts/{shiftid}
It is important to note that the shift id is the id of the overall shift, not the sub-shifts within the children array of the data object related to the shift.
You are able to update, remove and add children shifts as part of this process.
Sample Payload
{
"data": {
"shift": {
"area": 13,
"employee": 173,
"start": "2024-06-17T09:00:00+10:00",
"end": "2024-06-17T17:00:00+10:00",
"isOpen": false,
"mealbreakSlots": [
{
"slotType": "BREAK",
"state": 3,
"canStartEarly": true,
"canEndEarly": true,
"isMandatory": true,
"type": "MEAL_BREAK",
"start": 0,
"end": 900
}
],
"note": "",
"isPublished": false,
"approvalRequired": false,
"confirmationStatus": 0,
"confirmationNote": "",
"swapStatus": 0,
"shiftTemplate": null,
"children": [
{
"id": 39953,
"start": "2024-06-17T09:00:00+10:00",
"end": "2024-06-17T11:30:00+10:00",
"area": 13
},
{
"id": 39954,
"start": "2024-06-17T11:30:00+10:00",
"end": "2024-06-17T14:15:00+10:00",
"area": 62
},
{
"start": "2024-06-17T14:15:00+10:00",
"end": "2024-06-17T17:00:00+10:00",
"area": 63
}
],
"customFields": [
{
"id": 15,
"booleanField": {
"value": false
}
}
]
},
"override": {
"shiftValidation": true,
"publishValidation": false
}
}
}
In this example we are updating a child shift and adding another. You can see this by the fact that two of the children shift have the existing id attached to them, indicating to the Deputy system that we want to either keep those shifts as is or change them to what we have adjusted. In the third child we do not have an id indicating to the Deputy system that this is a new record to add to the overall shift. If you wanted to remove an existing sub-shift, just do not include it in the children array when sending the update API request.
Deleting a shift
To delete a shift including all shift plans use the following url.
URL
curl --DELETE --url 'https://{install}.{geo}.deputy.com/api/v2/management/shifts/{shiftid}
This will remove the entire shift from the Deputy system including any children shifts related to it.
Updated 3 months ago