Getting Data - Resources API
There are two main ways to interact with the Deputy API
- Using some of the more structured endpoints such as /supervise
- Using the Resource API to join data and perform more structured requests
Either way is fine but when dealing with large data sets of complex nature, the Resource API becomes the recommended option for retrieving data. This is because it allows you to fine-tune your request to specifically get the data that you need.
The Deputy API currently has a limitation of 500 items per response, and responses of that size can be extremely large. The Resource API allows you specifically target what you need. For example, you can use the Resource API to retrieve data after a specific date, or from a specific area.
One of the most powerful features of the resource API is the ability to combine queries together. So for example when retrieving timesheets from the TimesheetPayReturn object, you are able to also join the Timesheet object by Employee id allowing you to perform what would normally take two requests, in one.
Below we've stepped through this example to show how powerful the Resource API can be.
Getting a list of all worked time by a team example
https://{install}.{geo}.deputy.com/api/v1/resource/TimesheetPayReturn/QUERY
The method for the Resource API is always POST even if you are only retrieving data out.
The TimesheetPayReturn query returns timesheets from a Deputy install that have been approved and ready to be processed in a payroll system. By default, it will return a response like this
{
"Id": 1,
"Timesheet": 1,
"PayRule": 20,
"Overridden": false,
"Value": 11.5,
"Cost": 345,
"OverrideComment": "",
"Creator": 3,
"Created": "2022-05-07T14:08:14+10:00",
"Modified": "2022-05-07T14:08:14+10:00",
"_DPMetaData": {
"System": "TimesheetPayReturn",
"CreatorInfo": {
"Id": 3,
"DisplayName": "Carlos Smith",
"EmployeeProfile": 3,
"Employee": 3,
"Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1661970140&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=BX0TNakxrWahvELBnK~0WDbQld3ndBh1Jzz~3PWMePUirlq--TL65mDcrPuujE8C~SpDvUfIeOuCU9gOUBBRQDIK94EnZwgkqtK9zDQ4tJzw2WHn-m~M6uTsNcmLBwra6yskwwcM-te1qITEZRTaaLHX-SS741WMj4n8Y1-LGHE_",
"Pronouns": 0,
"CustomPronouns": ""
}
}
}
As you can see, this response has information about the value of the timesheet (which represents the hours) and the cost of the timesheet, which is the dollar cost for a payroll system to process.
At this point, you may need more information from the Deputy system such as is the timesheet leave based or not. Typically you would then need to query the Timesheet endpoint with the Timesheet id from this payload.
However, with the resource API it's possible to combine these queries together.
Combining queries using the Resource API
Combining queries with the Resource API is a matter of including a join element in the payload. This element includes the data you would like to join on as well as how you would like it to be sorted.
{
"sort": {
"Id": "asc"
},
"join": ["TimesheetObject"]
}
The above payload will join the Timesheets to the corresponding TimesheetPayReturn records and sort them in ascending order by the Id. A sample response is below
{
"Id": 1,
"Timesheet": 1,
"PayRule": 20,
"Overridden": false,
"Value": 11.5,
"Cost": 345,
"OverrideComment": "",
"Creator": 3,
"Created": "2022-05-07T14:08:14+10:00",
"Modified": "2022-05-07T14:08:14+10:00",
"_DPMetaData": {
"System": "TimesheetPayReturn",
"CreatorInfo": {
"Id": 3,
"DisplayName": "Carlos Sainz",
"EmployeeProfile": 3,
"Employee": 3,
"Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1661970140&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=BX0TNakxrWahvELBnK~0WDbQld3ndBh1Jzz~3PWMePUirlq--TL65mDcrPuujE8C~SpDvUfIeOuCU9gOUBBRQDIK94EnZwgkqtK9zDQ4tJzw2WHn-m~M6uTsNcmLBwra6yskwwcM-te1qITEZRTaaLHX-SS741WMj4n8Y1-LGHE_",
"Pronouns": 0,
"CustomPronouns": ""
}
},
"TimesheetObject": {
"Id": 1,
"Employee": 3,
"EmployeeHistory": 2586,
"EmployeeAgreement": 5,
"Date": "2022-05-06T00:00:00+10:00",
"StartTime": 1651791600,
"EndTime": 1651834800,
"Mealbreak": "2022-05-06T00:30:00+10:00",
"MealbreakSlots": {
"1651829880": "OUT",
"1651832340": "IN"
},
"Slots": [
{
"blnEmptySlot": false,
"strType": "B",
"intStart": 0,
"intEnd": 1800,
"intUnixStart": 1651791600,
"intUnixEnd": 1651793400,
"mixedActivity": {
"intState": 4,
"blnCanStartEarly": 1,
"blnCanEndEarly": 1,
"blnIsMandatory": 1,
"strBreakType": "M"
},
"strTypeName": "Meal Break",
"strState": "Finished Duration"
}
],
"TotalTime": 11.5,
"TotalTimeInv": 4.48,
"Cost": 345,
"Roster": 15,
"EmployeeComment": null,
"SupervisorComment": null,
"Supervisor": null,
"Disputed": false,
"TimeApproved": true,
"TimeApprover": 3,
"Discarded": null,
"ValidationFlag": 0,
"OperationalUnit": 1,
"IsInProgress": false,
"IsLeave": false,
"LeaveId": null,
"LeaveRule": null,
"Invoiced": false,
"InvoiceComment": null,
"PayRuleApproved": true,
"Exported": null,
"StagingId": 1,
"PayStaged": true,
"PaycycleId": 1,
"File": null,
"CustomFieldData": null,
"RealTime": true,
"AutoProcessed": true,
"AutoRounded": false,
"AutoTimeApproved": false,
"AutoPayRuleApproved": true,
"Creator": 3,
"Created": "2022-05-06T16:31:29+10:00",
"Modified": "2022-05-07T14:11:41+10:00",
"OnCost": 345,
"StartTimeLocalized": "2022-05-06T09:00:00+10:00",
"EndTimeLocalized": "2022-05-06T21:00:00+10:00",
"_DPMetaData": {
"System": "Timesheet",
"CreatorInfo": {
"Id": 3,
"DisplayName": "Carlos Sainz",
"EmployeeProfile": 3,
"Employee": 3,
"Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1661970140&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=BX0TNakxrWahvELBnK~0WDbQld3ndBh1Jzz~3PWMePUirlq--TL65mDcrPuujE8C~SpDvUfIeOuCU9gOUBBRQDIK94EnZwgkqtK9zDQ4tJzw2WHn-m~M6uTsNcmLBwra6yskwwcM-te1qITEZRTaaLHX-SS741WMj4n8Y1-LGHE_",
"Pronouns": 0,
"CustomPronouns": ""
},
"OperationalUnitInfo": {
"Id": 1,
"OperationalUnitName": "Chef",
"Company": 1,
"CompanyName": "Simons Sambos",
"LabelWithCompany": "[Sim] Chef"
},
"EmployeeInfo": {
"Id": 3,
"DisplayName": "Carlos Sainz",
"EmployeeProfile": 3,
"Employee": 3,
"Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1661970140&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=BX0TNakxrWahvELBnK~0WDbQld3ndBh1Jzz~3PWMePUirlq--TL65mDcrPuujE8C~SpDvUfIeOuCU9gOUBBRQDIK94EnZwgkqtK9zDQ4tJzw2WHn-m~M6uTsNcmLBwra6yskwwcM-te1qITEZRTaaLHX-SS741WMj4n8Y1-LGHE_",
"Pronouns": 0,
"CustomPronouns": ""
},
"CustomFieldData": null
}
}
}
As you can see the response is much larger but contains all the relevant information from the Timesheet. This means you are able to retrieve data in a single request, that using a more traditional request may have taken three or four to obtain.
The joined timesheet is attached as an object and contains all the data elements that would be returned from the Timesheet by Id endpoint.
Filtering data using the Resource API
Whilst joining objects can be a huge time saver for developers and cut down how many queries an application needs to run, it can also be used to filter data. In the below example, we are querying the Timesheet Resource API endpoint. We are filtering it to only include timesheets between the 1st of May and the 8th of May 2022.
{"search":{
"s1":{"field":"Date","data": "2022-05-01", "type": "gt"},
"s2":{"field":"Date","data": "2022-05-08", "type": "lt"}
}}
The search object allows you to define how you would like to filter this data. Multiple filters can be applied to a single search, this is handled by including "s" objects in a sequential order. So in the above example "s1" is searching for timesheets greater than (gt) 2022-05-01 and "s2" is searching for timesheets less than (lt) 2022-05-08.
If for example you wanted to filter based on an employee id of one you could use the following payload
{"search":{
"s1":{"field":"Employee","data": 1, "type": "eq"}
}}
So using this payload we've defined the field we wanted filter on is Employee, the data we want to filter on is 1 (meaning that we are looking for Employees with the id of 1 in this search) and using type eq which is equals.
Now combining both of these (searching for timesheets between May 1 and May 8 2022 with an Employee id of 1) you get the following payload
{"search":{
"s1":{"field":"Date","data": "2022-05-01", "type": "gt"},
"s2":{"field":"Date","data": "2022-05-08", "type": "lt"},
"s3":{"field":"Employee", "data":1, "type": "eq"}
}}
As you can see the Resource API can be used to filter data specifically to what your app requires, and this can help ensure you are performing the least amount of requests possible and not dealing with large payload responses.
Updated over 1 year ago
Find out more information including the available Resource API objects