Getting Shifts

Rosters form a key part of the Deputy ecosystem and like timesheets they can be in various different states. Rosters are also a part of the Deputy application which can have constant updates applied, for example a shift might become filled by an employee, employees may swap their shifts amongst themselves (if management approves) and draft shifts become published. This is important to take into account when determining how to build out your integration as what may have been true about a roster yesterday may not be so today.

By default, the roster information that the API provides is the next 36 hours and the previous 12 hours of scheduled shifts. So for example if you send a request at 2pm on a Tuesday, you will get the rosters up to 2am Thursday and the previous rosters back to 2am Tuesday.

In many cases however your requirements may not necessarily fit into this window and that is where the Resource API becomes useful. Using the resource API you are able to send much more targeted requests to Deputy such as obtaining all rosters between two particular dates, or only pulling out a specific employees scheduled shifts.

Getting the rosters/shifts for the next 7 days

In your application you may want to pull down and present information to the users about upcoming shifts. This can be achieved using the Resource API and defining the time period your application would like to retrieve.

URL

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v1/resource/Roster/QUERY'

By default this will return up to 500 records of shifts from the Deputy install, this is unlikely to give you exactly what you need, as most Deputy installs have more than 500 shifts within the system. To get around this, with the resource api you can provide queries to define time periods, employees or against any data element present within the response.

In the below example we are going to request the roster for the 1st of September 2022.

{"search":{
    "s1":{ "field": "Date", "data": "2022-09-01", "type": "eq"}
}}

In the payload we are defining that the field to search on is the Date, the date we are looking for is 2022-09-01 and the matching type is equals (eq).

This request will respond with all rosters/shifts from the specified date.

Sample response of roster/shifts

{
        "Id": 714,
        "Date": "2022-09-01T00:00:00+10:00",
        "StartTime": 1661986800,
        "EndTime": 1662028200,
        "Mealbreak": "2022-09-14T00:30:00+10:00",
        "Slots": [
            {
                "blnEmptySlot": false,
                "strType": "B",
                "intStart": 900,
                "intEnd": 2700,
                "intUnixStart": 1661987700,
                "intUnixEnd": 1661989500,
                "mixedActivity": {
                    "intState": 3,
                    "blnCanStartEarly": 1,
                    "blnCanEndEarly": 1,
                    "blnIsMandatory": 1,
                    "strBreakType": "M"
                },
                "strTypeName": "Meal Break",
                "strState": "Scheduled Duration"
            }
        ],
        "TotalTime": 11,
        "Cost": 220,
        "OperationalUnit": 1,
        "Employee": 2,
        "Comment": null,
        "Warning": "",
        "WarningOverrideComment": null,
        "Published": false,
        "MatchedByTimesheet": 184,
        "CustomFieldData": null,
        "Open": false,
        "ApprovalRequired": false,
        "ConfirmStatus": 0,
        "ConfirmComment": "",
        "ConfirmBy": 0,
        "ConfirmTime": 0,
        "SwapStatus": 0,
        "SwapManageBy": null,
        "ShiftTemplate": 1,
        "ConnectStatus": null,
        "Creator": 1,
        "Created": "2022-08-19T14:01:44+10:00",
        "Modified": "2022-09-01T09:09:41+10:00",
        "OnCost": 220,
        "StartTimeLocalized": "2022-09-01T09:00:00+10:00",
        "EndTimeLocalized": "2022-09-01T20:30:00+10:00",
        "ExternalId": null,
        "ConnectCreator": null,
        "_DPMetaData": {
            "System": "Roster",
            "CreatorInfo": {
                "Id": 1,
                "DisplayName": "Simon Hutchinson",
                "EmployeeProfile": 1,
                "Employee": 1,
                "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_1e4417bce8404f8facdfe89990f3bedb.jpg?Expires=1663212010&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=DBHhmBxVg9sv39xBHizAtaunOD~aBT~8OILB1vq6ja58BptvcH-a57FZ327Z~3JblNV0oD4CR4YEn1g2NNbT6dr66X-8LfuARWqkcNS3sBF2wzYIUWaE1QEvh4SvK4GEA1vJOya3bYpnRyOnlLgxvwgtRpGISZxjKrUpSYIfbFE_",
                "Pronouns": 0,
                "CustomPronouns": ""
            },
            "OperationalUnitInfo": {
                "Id": 1,
                "OperationalUnitName": "Chef",
                "Company": 1,
                "CompanyName": "Simons Sambos",
                "LabelWithCompany": "[Sim] Chef"
            },
            "EmployeeInfo": {
                "Id": 2,
                "DisplayName": "Sebastian Vettell",
                "EmployeeProfile": 2,
                "Employee": 2,
                "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_3f8b58630bffaf8fe2988c34ea255c0a.jpg?Expires=1663212010&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=FPRV9Ka0Q9MO-lOElkENC~9y20SwjfTC4ggTqe61wDrmP~U8le~RTcaiwjtkmNL7elPaPK1R1pP1a4S5PHe0qUqscW76vSFfZkIrjZnE-Nzyw2AyxJkmE4TvkRIMZds4agvEffHekG7eqI-dM-YW8GYqU33QXgYuTTf6iO3~OZA_",
                "Pronouns": 0,
                "CustomPronouns": ""
            },
            "SwapManageByInfo": []
        },
        "BidsCount": null
    }

Data Element Info

Data ElementInfo
IdThe id of the roster record
DateThe localised date and time of the roster stat time
StartTimeThe start time for the shift in unix time
EndTimeThe end time for the shift in unix time
MealbreakThe localised date and time for a meal break in the shift
Slots arrayIf a break is part of the shift, details will appear in this array
blnEmptySlotBoolean true/false. If a break exists in the shift this will always be false
strTypeWhat type of slot entry this is. B = Break W = Worked.
intStartIn unix ticks how far into the shift is the break taken
intEndIn unix ticks how far into the shift is the break ended
intUnixStartIn unix ticks what time the break states
intUnixEndIn unix ticks what time the break ends
MixedActivity ObjectContains information about the break such as whether it can be taken early etc.
intStateThe state of the break. 3 = Break not taken yet and has scheduled duration. 2 is finished without specified duration. 4 is finished and had specified duration.
blnCanStartEarlyBoolean. 0 if this is not allowed 1 if this is allowed. Whether the employee is allowed to start their break early
blnCanEndEarlyBoolean. 0 if this is not allowed 1 if this is allowed. Whether the employee is allowed to end their break early.
blnIsMandatoryBoolean. 0 if the break is not mandatory, 1 if the break is mandatory.
strBreakTypeThe type of break in this slot. M if meal break R if rest break.
strTypeNameA string name of the break type eg. "Meal Break"
strStateA string name of the current state of the break.
TotalTimeThe total time of the shift
CostThe cost in dollars of the shift
OperationalUnitThe id record of the Deputy location that the shift is recorded against
EmployeeThe id record number of the employee assigned to the shift
CommentIf a comment is entered against the shift it will appear here as a string
Warning
WarningOverrideCommentIf a warning was over ridden, and a comment was entered as to why, it will appear here as a string
PublishedBoolean true/false. Whether the shift is published or not.
MatchByTimesheetThe id record of the timesheet linked to this shift
CustomFieldDataIf any custom field data is present in the record, it will appear here
PublishedBoolean true/false. Whether the shift is published or not
OpenWhether the shift is open. An open shift indicates an employee has not been allocated to the shift as yet.
ApprovalRequiredBoolean true/false. Whether a manager approval is required for the shift
ConfirmStatus
ConfirmComment
ConfirmBy
ConfirmTime
SwapStatus
SwapManageBy
ShiftTemplate
ConnectStatus
CreatorThe id record of the employee who created the shift
CreatedThe date and time the shift was created in the Deputy system localised to timezone
ModifiedThe date and time the record was last modified localised to timezone
OnCostThe total dollar cost of the shift
StartTimeLocalizedWhen the shift starts in unix time
EndTimeLocalizedThe the shift ends in unix time
OperationalUnitInfo ObjectThis object contains information about which area and location the shift is linked to
IdThe id record number of the shift
OperationalUnitNameThe name of the area the shift is linked to as a string
CompanyThe id record of the location that the shift is related to
CompanyNameThe name of the location as a string
LabelWithCompanyA string combining the shortened location name with the area name.