Creating or Updating a Timesheet

Once a timesheet is sent through to a payroll system, a manager may review it and feel its incorrect or alternately there may be times where an employee has forgotten to do a timesheet and a manager wants to add it from another application. This is all possible via the Deputy API where developers have the ability to not only update but also create timesheets from scratch.

Below are some code examples of how to update and create timesheets in the Deputy application using the Deputy API

Creating a timesheet via the API

When creating a timesheet in the Deputy application, there is a number of data elements which need to be known before this request can be made. Your application will need to know the following information:

  • The start and stop time of the timesheet
  • Whether any meal or rest break was taken
  • Optionally, whether the employee was able to start the shift early, end the shift early and whether a break was mandatory.

If you intend to offer the ability to create timesheets remotely in Deputy from your app, you will need to think about how to capture that data.

Below is a simple example of adding a timesheet to the Deputy install via the API.

URL

curl --request POST --url 'https://{install}.{geo}.deputy.com/api/v1/supervise/timesheet'

Sample request to add a timesheet

{
    "intEmployeeId": 1,
    "intOpunitId": 2,
    "intStartTimestamp": 1616360400,
    "intEndTimestamp": 1616382000,
    "arrSlots": [{
        "blnEmptySlot": false,
        "strType": "B",
        "intStart": 7200,
        "intEnd": 9000,
        "intUnixStart": 1616367600,
        "intUnixEnd": 1616369400,
        "mixedActivity": {
            "intState": 2,
            "blnCanStartEarly": 1,
            "blnCanEndEarly": 1,
            "blnIsMandatory": 1,
            "strBreakType": "M"
        },
        "strTypeName": "Meal Break",
        "strState": "Finished"
    }]
}

Data Elements

Data ElementInfo
intEmployeeIdThe id record of the employee for who the timesheet is for.
intOpUnitIdThe id of the location who the timesheet is for
intStartTimestampThe unix time of the start of the timesheet
intEndTimestampThe unix time of the end of the timesheet
arrSlotsThis contains information about any breaks that may have occured during the time period
blnEmptySlotIf including data in this array always false as the slot exists
strTypeThe type of slot. For breaks use B
intStartThis is how much time has elapsed into the shift before the break started. So in the example 7200 ticks.
intEndThis is how much time has elapsed into the shift when the break ended. So in the example 9000 ticks.
intUnixStartThe start timestamp of the break in unix time
intUnixEndThe end timestamp of the break in unix time
mixedActivity objectThis object gives information about the break itself such as can the employee choose to take it early.
intStateThe 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.
blnCanStartEarlyBoolean. 1 if break is allowed to start earlier than scheduled, 0 if not allowed.
blnCanEndEarlyBoolean.1 if break is allowed to end earlier than scheduled, 0 if not allowed.
blnIsMandatoryWhether the break should be considered mandatory. 1 if mandatory, 0 if not.
strBreakTypeThe type of break.

M - Meal break

R - Rest break

Sample response when adding a timesheet via the API

{
    "Id": 257,
    "Employee": 1,
    "EmployeeHistory": 105907,
    "EmployeeAgreement": 3,
    "Date": "2021-03-22T00:00:00+11:00",
    "StartTime": 1616360400,
    "EndTime": 1616382000,
    "Mealbreak": "2021-03-22T00:00:00+11:00",
    "MealbreakSlots": {
        "1616367600": "OUT",
        "1616369400": "IN"
    },
    "Slots": [
        {
            "blnEmptySlot": false,
            "strType": "B",
            "intStart": 7200,
            "intEnd": 9000,
            "intUnixStart": 1616367600,
            "intUnixEnd": 1616369400,
            "mixedActivity": {
                "intState": 2,
                "blnCanStartEarly": 1,
                "blnCanEndEarly": 1,
                "blnIsMandatory": 1,
                "strBreakType": "M"
            },
            "strTypeName": "Meal Break",
            "strState": "Finished"
        }
    ],
    "TotalTime": 6,
    "TotalTimeInv": 6,
    "Cost": null,
    "Roster": null,
    "EmployeeComment": null,
    "SupervisorComment": null,
    "Supervisor": null,
    "Disputed": false,
    "TimeApproved": false,
    "TimeApprover": null,
    "Discarded": null,
    "ValidationFlag": 0,
    "OperationalUnit": 2,
    "IsInProgress": false,
    "IsLeave": false,
    "LeaveId": null,
    "LeaveRule": null,
    "Invoiced": false,
    "InvoiceComment": null,
    "PayRuleApproved": false,
    "Exported": null,
    "StagingId": null,
    "PayStaged": false,
    "PaycycleId": 78,
    "File": null,
    "CustomFieldData": null,
    "RealTime": 0,
    "AutoProcessed": 0,
    "AutoRounded": 0,
    "AutoTimeApproved": 0,
    "AutoPayRuleApproved": 0,
    "Creator": 3,
    "Created": "2022-09-11T12:51:23+10:00",
    "Modified": "2022-09-11T12:51:23+10:00",
    "OperationalUnitObject": {
        "Id": 2,
        "Creator": 1,
        "Created": "2022-05-05T16:43:57+10:00",
        "Modified": "2022-09-02T13:52:01+10:00",
        "Company": 1,
        "WorkType": null,
        "ParentOperationalUnit": 0,
        "OperationalUnitName": "Cashier",
        "Active": true,
        "PayrollExportName": "",
        "Address": 158,
        "Contact": null,
        "RosterSortOrder": 1,
        "ShowOnRoster": true,
        "Colour": null,
        "RosterActiveHoursSchedule": null,
        "DailyRosterBudget": null,
        "OperationalUnitType": 1,
        "AddressObject": {
            "Id": 158,
            "ContactName": null,
            "UnitNo": null,
            "StreetNo": null,
            "SuiteNo": null,
            "PoBox": null,
            "Street1": "90 Pacific St, Kiama NSW 2533, Australia",
            "Street2": null,
            "City": null,
            "State": null,
            "Postcode": null,
            "Country": 13,
            "Phone": null,
            "Notes": null,
            "Format": null,
            "Saved": null,
            "Creator": 1,
            "Created": "2022-05-05T16:43:57+10:00",
            "Modified": "2022-05-05T16:43:57+10:00",
            "Print": "90 Pacific St, Kiama NSW 2533, Australia\n"
        },
        "CompanyCode": "Sim",
        "CompanyName": "Simons Sambos",
        "CompanyAddress": 157
    },
    "OnCost": 0,
    "StartTimeLocalized": "2021-03-22T08:00:00+11:00",
    "EndTimeLocalized": "2021-03-22T14:00:00+11: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=1662947704&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=aXV4TVZHVAYNoYe6NLvgIkujV6kNjS5jmNkFwzlEhy0fZCS7qHvwBSQK5pMOU2xcpAWv3E6nIPuPxgj-eHOVf3uHWoRAT649EcW94OAPAL6kgdpNIUp8MiO1MNBUUY3ARgZ2gz5pzNKtIVVBToSsqiqW2xQQObH6goTMwPlMlXg_",
            "Pronouns": 4,
            "CustomPronouns": "Carlos"
        },
        "OperationalUnitInfo": {
            "Id": 2,
            "OperationalUnitName": "Cashier",
            "Company": 1,
            "CompanyName": "Simons Sambos",
            "LabelWithCompany": "[Sim] Cashier"
        },
        "EmployeeInfo": {
            "Id": 1,
            "DisplayName": "Simon Hutchinson",
            "EmployeeProfile": 1,
            "Employee": 1,
            "Photo": "https://photo2.deputy.com/deputec_b220505063318_11516/-135x135_1e4417bce8404f8facdfe89990f3bedb.jpg?Expires=1662938013&Key-Pair-Id=APKAINP5UVPK4IGBHXOQ&Signature=HucgElDpUN2nval4W9JDkeEytACcyxlm0-soF-Yqzsufal5evb4ibu4gZXhGZANw265oPFklFeP3u3La5gIYl1EE4Hd2Li88ZaB0sAh4OyNNjnI91esVzDpHyj-4691ILLFa6F~CjHAe4wvL4EXDuYXAeOQh4FNl843Sp8liv~Q_",
            "Pronouns": 0,
            "CustomPronouns": ""
        },
        "CustomFieldData": null
    },
    "CanEdit": true
}

The response is very much the same as that when you are retrieving existing timesheets as detailed in the Getting Timesheets from Deputy guide.

Updating an existing timesheet

The process to update an existing timesheet, is exactly the same as adding a new one (same URL for example) with one key difference. The id record of the timesheet to be updated is included in the payload. Example below

{
    intTimesheetId: 1,
    intStartTimestamp: 1616360400,
    intEndTimestamp: 1616382000,
    intOpunitId: 2,
    strComment: "This timesheet was recently updated via the API"
}

In this example, the timesheet with the id record of 1 is having its start time, stop time and location updated, with a comment included that the timesheet was updated by the API.