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 ElementInfo
successWhether 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)
dataThe array which contains the shift/shift plans objects which makes up the response
idThe id record of the shift/shift plans
startThe start time of the shift including timezone
endThe end time of the shift including timezone
mealbreakDurationThe length in hours (decimal) that breaks have been scheduled for the shift
mealbreakSlotsArray containing information about meal breaks scheduled in the shift
mealbreakSlots - slotTypeThe type of slot
mealbreakSlots - startThe 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 - endThe end time of the scheduled mealbreak in unix ticks after the start of the shift.
mealbreakSlots - stateThis 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- canStartEarlyBoolean true/false - Defines whether when a meal break has been specifically scheduled if the employee is allowed to start that break early
mealbreakSlots- canEndEarlyBoolean true/false - Defines once the meal break has started whether an employee is allowed to clock back into the shift early
mealbreakSlots - isMandatoryBoolean true/false - Defines whether the break must be taken as part of the shift.
mealbreakSlots - typeThe type of break
mealbreakSlots - typeLabelThe label of the type of the break
durationThe duration of the shift in hours decimal
costThe cost of the shift. This is only calculated once a timesheet generated from the shift is approved.
areaThe id record number of the area related to the shift
employeeThe id record number of the employee related to the shift
noteAny note added to the shift by the manager
warningAny warning in text that the manager was presented before approving the shift for publish
warningOverrideCommentAny comment related to why a shift warning was overriden by a manager.
isPublishedBoolean true/false - whether the shift is published or draft
timesheetIf a timesheet exists linked to the shift its record id will appear here
isOpenWhether the shift is open and no employee assigned yet
approvalRequiredWhether an employee has to confirm the shift for it to be valid
confirmationStatusText about the status of the shift confirmation
confirmationNoteIf an employee has confirmed a shift and added a note it will be added here
confirmedByWhomIf an employee has confirmed a shift the record id for the employee will be added here
confirmedAtIf an employee has confirmed a shift the timestamp of when the employee confirmed the shift
swapStatusWhether the shift is allowed to be swaped
shiftTemplate
childrenThis 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 - idThe id record number of the sub-shift
children - startThe start time including timezone of the sub-shift
children - costThe cost of the sub-shift. This will not be available until a timesheet related to the sub-shift is approved.
children - areaThe record id of the area the sub-shift is for
children - employeeThe record id of the employee the sub-shift is for
children - noteAny note attached to the sub-shift
children - warningAny warning in text related to the sub-shift
children - warningOverrideCommentAny comment in text as to why the warning was overridden
children - isPublishedBoolean true/false. Whether the sub-shift is published
children - timesheetIf there is a timesheet related to the sub-shift, the timesheet record id will appear here
children - isOpenWhether an employee is assigned to the sub-shift or not
children - approvalRequiredWhether an employee has to confirm the shift
children - confirmationStatusStatus of the shift in terms of confirmation if it has been required
children - confirmationNoteIf the employee when confirming the sub-shift has added a note it will appear here
children - confirmedByWhomThe record id number of the employee who confirmed the sub-shift. 0 if not required
children - confirmedAtThe time including timezone the shift was confirmed. Blank if not required or not confirmed
children - swapStatusThe swap status of the sub-shift
children- shiftTemplate
canEditWhether the shift can be edited
customFieldsAny custom fields related to the shift, primarily from our Enterprise product
customFieldDataIf custom fields exist on the response this will be 1
creatorThe record id of the user who created the shift
createdAtThe time including timezone as to when the shift was created
modifiedAtThe time including timezone as to when the shift was last modified
consentChangesetsAny changes related to consent and Fair Work Week that has been related to this shift.
nextCursorIn 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

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.

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.