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 Element | Info |
|---|---|
| Id | The id of the roster record |
| Date | The localised date and time of the roster stat time |
| StartTime | The start time for the shift in unix time |
| EndTime | The end time for the shift in unix time |
| Mealbreak | The localised date and time for a meal break in the shift |
| Slots array | If a break is part of the shift, details will appear in this array |
| blnEmptySlot | Boolean true/false. If a break exists in the shift this will always be false |
| strType | What type of slot entry this is. B = Break W = Worked. |
| intStart | In unix ticks how far into the shift is the break taken |
| intEnd | In unix ticks how far into the shift is the break ended |
| intUnixStart | In unix ticks what time the break states |
| intUnixEnd | In unix ticks what time the break ends |
| MixedActivity Object | Contains information about the break such as whether it can be taken early etc. |
| intState | The 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. |
| blnCanStartEarly | Boolean. 0 if this is not allowed 1 if this is allowed. Whether the employee is allowed to start their break early |
| blnCanEndEarly | Boolean. 0 if this is not allowed 1 if this is allowed. Whether the employee is allowed to end their break early. |
| blnIsMandatory | Boolean. 0 if the break is not mandatory, 1 if the break is mandatory. |
| strBreakType | The type of break in this slot. M if meal break R if rest break. |
| strTypeName | A string name of the break type eg. "Meal Break" |
| strState | A string name of the current state of the break. |
| TotalTime | The total time of the shift |
| Cost | The cost in dollars of the shift |
| OperationalUnit | The id record of the Deputy location that the shift is recorded against |
| Employee | The id record number of the employee assigned to the shift |
| Comment | If a comment is entered against the shift it will appear here as a string |
| Warning | |
| WarningOverrideComment | If a warning was over ridden, and a comment was entered as to why, it will appear here as a string |
| Published | Boolean true/false. Whether the shift is published or not. |
| MatchByTimesheet | The id record of the timesheet linked to this shift |
| CustomFieldData | If any custom field data is present in the record, it will appear here |
| Published | Boolean true/false. Whether the shift is published or not |
| Open | Whether the shift is open. An open shift indicates an employee has not been allocated to the shift as yet. |
| ApprovalRequired | Boolean true/false. Whether a manager approval is required for the shift |
| ConfirmStatus | |
| ConfirmComment | |
| ConfirmBy | |
| ConfirmTime | |
| SwapStatus | |
| SwapManageBy | |
| ShiftTemplate | |
| ConnectStatus | |
| Creator | The id record of the employee who created the shift |
| Created | The date and time the shift was created in the Deputy system localised to timezone |
| Modified | The date and time the record was last modified localised to timezone |
| OnCost | The total dollar cost of the shift |
| StartTimeLocalized | When the shift starts in unix time |
| EndTimeLocalized | The the shift ends in unix time |
| OperationalUnitInfo Object | This object contains information about which area and location the shift is linked to |
| Id | The id record number of the shift |
| OperationalUnitName | The name of the area the shift is linked to as a string |
| Company | The id record of the location that the shift is related to |
| CompanyName | The name of the location as a string |
| LabelWithCompany | A string combining the shortened location name with the area name. |
Updated 10 months ago