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/update'

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 Element	Info
intEmployeeId	The id record of the employee for who the timesheet is for.
intOpUnitId	The id of the location who the timesheet is for
intStartTimestamp	The unix time of the start of the timesheet
intEndTimestamp	The unix time of the end of the timesheet
arrSlots	This contains information about any breaks that may have occured during the time period
blnEmptySlot	If including data in this array always false as the slot exists
strType	The type of slot. For breaks use B
intStart	This is how much time has elapsed into the shift before the break started. So in the example 7200 ticks.
intEnd	This is how much time has elapsed into the shift when the break ended. So in the example 9000 ticks.
intUnixStart	The start timestamp of the break in unix time
intUnixEnd	The end timestamp of the break in unix time
mixedActivity object	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	Boolean. 1 if break is allowed to start earlier than scheduled, 0 if not allowed.
blnCanEndEarly	Boolean.1 if break is allowed to end earlier than scheduled, 0 if not allowed.
blnIsMandatory	Whether the break should be considered mandatory. 1 if mandatory, 0 if not.
strBreakType	The 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 two key differences. The id record of the timesheet to be updated is included in the payload and update on the end of the URL. Example below

URL

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

{
    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.