Getting Timesheets from Deputy

Timesheets are a key part of the Deputy system and can be in many different states in the system. Which set you should retrieve is going to be driven primarily by your application use case. For example, if you have a payroll app, it is likely you would only want to retrieve those timesheets which have been approved for payroll and ignore those which are in a draft state. All of this is possible with the Deputy API.

Timesheets can be retrieved in a bulk manner as well as on an individual basis. The best way to retrieve timesheets is using the Resource API endpoint.

There are two key endpoints available in the resource API for Timesheets:

Timesheet : This endpoint gives detailed information about each timesheet. Items such as whether a break was taken, is the timesheet in progress (ie. the employee is currently on shift) and any comments that may be related to the timesheet are just a few of the data elements available.
TimesheetPayReturn : This endpoint works hand in hand with the Timesheet endpoint and gives information around the financials of a timesheet. For example what Deputy pay rule was applied to the timesheet, how much the timesheet cost in dollar terms and whether the timesheet has been overridden by a manager.

Each of the endpoints has its own unique purposes and it is likely that to get all of the most useful data for timesheets, you will be building a link to both of them. Both of these endpoints are detailed below, as well as a guide on how you can use the power of the Resource API to combine the two requests into one.

Getting timesheet data from Deputy

This code walkthrough will take you through line by line how to specifically target an employees timesheets for a time period.

🕘

Search for an employees timesheets with a date defined

Open Recipe

If the key information you want to get from timesheets in Deputy is data such as the employees name, hours they worked, whether a meal break was taken and the what state the timesheet is in (for example draft or in progress) then this is the endpoint to start with.

URL

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

By default this will return you the first 500 timesheets in the Deputy instance. It is likely you will be wanting to add some filtering to the request to target specific time frames. Below is a sample payload to show this.

{
  "search": {
    "s1": {"field": "StartTime", "data": 1651791600, "type": "gt" }
  }
}

This payload is searching for all timesheets where the start time is greater than 1651791600 in unix time. When you run this payload a request like the following will be returned. For simplification reasons we will focus on one response, but it is likely you will receive multiple timesheets objects back in the one request.

Sample Response

"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": "AdamRhys Sapo",
                "EmployeeProfile": 3,
                "Employee": 3,
                "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1662765191&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=NciTc-O2aFxvvE23YrP3XkGqqPAtXMJSbAoZ8NQNENtKVTt1hXPHmGiW~Y59KRhpUbjFH08iIybrmH5f8NeSXn0q5RSMdXo0c2KyyYUoCecX97pa1eOqLTEmc6kaPJhiDLXt86~-4BaNvpK20eVa0WZkk4TQL5SgPi7w3skT7jE_",
                "Pronouns": 4,
                "CustomPronouns": "Carlos"
            },
            "OperationalUnitInfo": {
                "Id": 1,
                "OperationalUnitName": "Chef",
                "Company": 1,
                "CompanyName": "Simons Sambos",
                "LabelWithCompany": "[Sim] Chef"
            },
            "EmployeeInfo": {
                "Id": 3,
                "DisplayName": "AdamRhys Sapo",
                "EmployeeProfile": 3,
                "Employee": 3,
                "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1662765191&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=NciTc-O2aFxvvE23YrP3XkGqqPAtXMJSbAoZ8NQNENtKVTt1hXPHmGiW~Y59KRhpUbjFH08iIybrmH5f8NeSXn0q5RSMdXo0c2KyyYUoCecX97pa1eOqLTEmc6kaPJhiDLXt86~-4BaNvpK20eVa0WZkk4TQL5SgPi7w3skT7jE_",
                "Pronouns": 4,
                "CustomPronouns": "Carlos"
            },
            "CustomFieldData": null
        }
    }
]

Data Elements

Data Element	Info
Id	The id record number of the timesheet
Employee	The id of the employee the timesheet is associated with.
EmployeeHistory	The id record of the employees history.
EmployeeAgreement	The id record of the employee agreement. The employee agreement details can be retrieved using the Resource API and the EmployeeAgreement endpoint.
Date	The date of the timesheet
StartTime	The start time of the timesheet in unix time
EndTime	The end time of the timesheet in unix time. Will be null if the timesheet is in progress (ie. the employee is currently on shift and has not clocked out)
MealBreak	If a meal break was taken as part of the timesheet, the time of the meal break.
MealbreakSlots	If a meal break was taken, this object will contain the start and end time of the break in unix time
MealbreakSlots - OUT	The time the employee clocked out for their meal break in unix time
MealbreakSlots - IN	The time the employee clocked in for their meal break in unix time
Slots Array	When meal break(s) are present, this array with give specific information about those breaks. For each break taken, an object will exist in this array.
blnEmptySlot	Boolean which informs whether this is an empty break slot.
strType	The type of break. B = Break W = Worked time
intStart	Always 0. This is used to calculate the specific length. of the break
intEnd	This number is the unix ticks since the break started. This can be used to help determine how long the break was.
intUnixStart	The unix timestamp of when the break started
intUnixEnd	The unix timestamp of when the break ended
mixedActivityObject	This object gives information about the break itself such as can the employee choose to take it early.
intState	The state of the break. 0 - Not started yet 1 - In progress. Employee has started break 2- A break has been taken and has both a start and end time. 3 - A scheduled break which is yet to start 4 - Finished break however the time may be different to the defined break at roster publish time because employee was allowed to take early or late etc.
blnCanStartEarly	If 1 employee is allowed to take early if 0 employee must take the break at designated time
blnCanEndEarly	If 1 employee is allowed to end their break early if 0 employee must return from break at designated time
blnIsMandatory	If 1 employee must take a break during the shift if 0 the employee is able to skip a break.
strBreakType	R = Rest break M = Meal break
strTypeName	By default this will be Meal Break. Users can however define this in their Deputy install settings so it may be different.
strStates	Defines the current start of the break 0 - Not started 1 - In progress 2 - Finished 3 - Duration only
TotalTime	The total time for the timesheet in hours
Cost	The cost of the timesheet based on the employees pay rates
Roster	The id record for the roster where this timesheet links to
EmployeeComment	If the employee has added a comment when saving the timesheet it will appear here
SupervisorComment	If the supervisor has added a comment to the timesheet it will appear here
Disputed	Boolean True/False - Whether the timesheet is currently in a disputed state. Depending on use case you may want to ignore these.
TimeApproved	Boolean True/False - Whether the time of the timesheet has been approved by a supervisor
TimeApprover	The id record for the employee who approved the timesheet
Discarded	Generally null unless timesheet has been voided
ValidationFlag
OperationalUnit	The id record of the location the timesheet is associated with from the Deputy install. Use Get location by id endpoint to find information about the location.
IsInProgress	Boolean True/False - Will be true if the timesheet is currently in progress (ie the employee is currently on shift)
IsLeave	Boolean True/False - Will be true if this is a leave timesheet. This is important to know because when this is true, you may need to retrieve information about the leave depending on your use case.
LeaveId	If isLeave is true, this will have the id record number of the leave item which relates to this timesheet
LeaveRule	If isLeave is true, this will have the id record number of the leave rule which relates to this timesheet
Invoiced
InvoiceComment
PayRuleApproved	Boolean True/False - Whether the timesheet is approved for payroll export. A timesheet can be in an approved state however not approved for payroll. In this case this will be false.
Exported	Will be null if the timesheet has not been exported. Contains unix timestamp of export if it has been exported.
PayStaged
PayCycleId	Id record of the paycycle that was used for this timesheet. Generally only used for Enterprise installs
File	Internal use only
CustomFieldData	If any custom field data has been included in this timesheet, it will appear here. This is generally only an Enterprise feature
RealTime	Whether the timesheet is considered real time. Ie the time was captured through an employee clocking on and off and not just a manual entry
AutoProcessed	Boolean True/False - Whether the timesheet was automatically generated by the employee clocking in and out.
AutoRounded	Boolean True/False - If any automatic rounding of minutes has occurred on the timesheet when it was saved.
AutoTimeApproved	Boolean True/False - Whether the time was automatically approved by the system or a supervisor had to approve it.
AutoPayRuleApproved	Whether the pay rule associated with the timesheet was automatically approved. ie The pay rule linked to the timesheet was automatically allowed to be applied, for the timesheet to then be approved for payroll export.
Creator	The id of the employee who created the record
Created	When the timesheet was created
Modified	When the timesheet was last modified
OnCost	The total cost of the timesheet
StartTimeLocalized	The localised start time for the timesheet based on the geo location of the Deputy customer
EndTimeLocalized	The localised end time for the timesheet based on the geo location of the Deputy customer

Retrieving the payment details of a Timesheet

If your use case only cares about the specific cost of a timesheet (perhaps a costings analytics tool) you can use the TimesheetPayReturn object as part of the Resource API which returns a simplified object focusing on what pay rule was used in the timesheet and how much it cost. Only timesheets approved for payroll will be returned in these requests.

URL

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

Using this endpoint will return the first 500 records so again it is likely you will need to include some filtering as part of the request. In the below example we are going to return timesheets greater than the date of the 1st of June 2022. We are also including a wildcard % at the end to indicate the hours and minutes do not matter.

{
  "search": {
    "s1": {"field": "Created", "data": "2022-06-01%", "type": "gt" }
  }
}

Sample Response

{
        "Id": 34,
        "Timesheet": 57,
        "PayRule": 128,
        "Overridden": false,
        "Value": 1.17,
        "Cost": 58.5,
        "OverrideComment": "",
        "Creator": 1,
        "Created": "2022-06-08T13:43:19+10:00",
        "Modified": "2022-06-08T13:43:19+10:00",
        "_DPMetaData": {
            "System": "TimesheetPayReturn",
            "CreatorInfo": {
                "Id": 1,
                "DisplayName": "Simon Hutchinson",
                "EmployeeProfile": 1,
                "Employee": 1,
                "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_1e4417bce8404f8facdfe89990f3bedb.jpg?Expires=1662754849&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=FS-YUV9VYA3~gRfoAi01C~NgsxWVAPANzagTkc-l0qjCAy7eMi-4Y1bGTGKP~wwRy35W-RRsy09t3DQl~R0lYg7t7j70LtWfWIPGBoV6tdqOKwaOwIPAKUvnQlnkQGaTgAL4sMMcvjrYk9wlM~X2A1M7arb~AuZst7gVa6N2694_",
                "Pronouns": 0,
                "CustomPronouns": ""
            }
        }
    }

Data Elements

Data Element	Info
Id	The id record of the TimesheetPayReturn record
PayRule	The id of the PayRule which has been used for this timesheet
Overridden	Boolean True/False Whether the timesheet has been overridden by a supervisor
Value	The length of the timesheet in hours. For example 11.5 is eleven and a half hours.
Cost	The labor cost of the timesheet in dollars.
OverrideComment	Any comment that has been added as to why the timesheet has been overridden
Creator	The id record of the employee that generated the record
Created	When the record was created
Modified	When the record was last modified

Combining the requests using the Resource API

As you can see the Timesheet endpoint gives very specific details about the timesheet, whilst the TimesheetPayReturn endpoint focuses on the payroll and cost aspect. On the face of it, most people would think the easiest way to get all the information is to run two sequential requests on each endpoint and combine the data.

However using the power of the Deputy Resource API, its possible to get all this data combined in a single request by joining the TimesheetObject to the TimesheetPayReturn request. Below is a guide on how to do this

URL

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

The request is made to the same endpoint as was done for the TimesheetPayReturn data, however this time, the body of the request contains an additional data element, called join. Using joins, with the Resource API its possible to perform requests over multiple data points and have a combined response returned.

Sample Request

{
  "search": {
    "s1": {"field": "Id", "data": 1, "type": "eq" }
  },
  "join": ["TimesheetObject"]
}

What this request does, is searches the TimesheetPayReturn endpoint but then also looks for the data from the Timesheet endpoint via the TimesheetObject join. This is one of the most powerful features of the Resource API allowing you to combine multiple queries into one payload.

Sample combined response

[
    {
        "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": "AdamRhys Sapo",
                "EmployeeProfile": 3,
                "Employee": 3,
                "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1662765191&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=NciTc-O2aFxvvE23YrP3XkGqqPAtXMJSbAoZ8NQNENtKVTt1hXPHmGiW~Y59KRhpUbjFH08iIybrmH5f8NeSXn0q5RSMdXo0c2KyyYUoCecX97pa1eOqLTEmc6kaPJhiDLXt86~-4BaNvpK20eVa0WZkk4TQL5SgPi7w3skT7jE_",
                "Pronouns": 4,
                "CustomPronouns": "Carlos"
            }
        },
        "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": "AdamRhys Sapo",
                    "EmployeeProfile": 3,
                    "Employee": 3,
                    "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1662765191&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=NciTc-O2aFxvvE23YrP3XkGqqPAtXMJSbAoZ8NQNENtKVTt1hXPHmGiW~Y59KRhpUbjFH08iIybrmH5f8NeSXn0q5RSMdXo0c2KyyYUoCecX97pa1eOqLTEmc6kaPJhiDLXt86~-4BaNvpK20eVa0WZkk4TQL5SgPi7w3skT7jE_",
                    "Pronouns": 4,
                    "CustomPronouns": "Carlos"
                },
                "OperationalUnitInfo": {
                    "Id": 1,
                    "OperationalUnitName": "Chef",
                    "Company": 1,
                    "CompanyName": "Simons Sambos",
                    "LabelWithCompany": "[Sim] Chef"
                },
                "EmployeeInfo": {
                    "Id": 3,
                    "DisplayName": "AdamRhys Sapo",
                    "EmployeeProfile": 3,
                    "Employee": 3,
                    "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_45ca58e0db1a271fda5c83c399f7221a.jpg?Expires=1662765191&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=NciTc-O2aFxvvE23YrP3XkGqqPAtXMJSbAoZ8NQNENtKVTt1hXPHmGiW~Y59KRhpUbjFH08iIybrmH5f8NeSXn0q5RSMdXo0c2KyyYUoCecX97pa1eOqLTEmc6kaPJhiDLXt86~-4BaNvpK20eVa0WZkk4TQL5SgPi7w3skT7jE_",
                    "Pronouns": 4,
                    "CustomPronouns": "Carlos"
                },
                "CustomFieldData": null
            }
        }
    }
]

As you can see, the data which comes from the Timesheet endpoint has been appended to this response in an object called TimesheetObject. This allows you to retrieve all the timesheet data available in Deputy in a single request.