📘
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

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.

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.

📘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

Getting the rosters/shifts for the past 7 days

URL

URL

Sample Response

Data Element Info

Adding a shift with shift plans to Deputy

URL

Sample Payload - One Location

Sample Payload - Shift between 9am and 5pm which has multiple locations for shift plans

Updating an existing shift

URL

Sample Payload

Deleting a shift

URL

📘
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.