Create, Update and Deleting Timesheets

It’s great to see a number of payroll-related integrations using our Timesheet endpoint. We do get a few queries from time to time around this resource so I thought I’d put together a short article on timesheets. to touch on this unique endpoint and how it differs in terms of HTTP operators and functionality.

Can I POST new Timesheets?

The short answer here is YES absolutely you can however to create a new timesheet record you do not use the standard POST operator to do this. Instead, the PUT operator is substituted in it’s place combined with the Employee.UID to generate a new timesheet.

Illustrated in the below example shows the PUT  operator in action creating a timesheet for my employee API TEST. The Employee.UID is passed on the end of the url and also included in the JSON body of the request.

> PUT /{domain}/{cf guid}//Payroll/Timesheet/{Employee UID}

| {
| "Employee": {
| "UID": "974c9258-90dd-462f-8463-c81022b47504",
| "Name": "API Test",
| "URI": "https://arl2.api.myob.com/accountright/dcc6be7f-6e9e-4c5e-b14d-470e70XXXXXX/Contact/Employee/974c9258-90dd-462f-8463-c81022b47504"
| },
| "StartDate": "2022-11-23T00:00:00Z",
| "EndDate": "2022-11-29T00:00:00Z",
| "Lines": [
| {
| "PayrollCategory": {
| "UID": "9a225943-c852-44bc-8bc2-7cf21e78f317",
| "Name": "Base Hourly",
| "Type": "Wage",
| "URI": "https://arl2.api.myob.com/accountright/dcc6be7f-6e9e-4c5e-b14d-470eXXXXXXXX/Payroll/PayrollCategory/Wage/9a225943-c852-44bc-8bc2-7cf21e78f317"
| },
| "Job": null,
| "Activity": null,
| "Customer": null,
| "Notes": "",
| "Entries": [
| {
| "UID": "00000000-0000-0000-0000-000000000000",
| "Date": "2022-11-23T00:00:00",
| "Hours": 8.000000,
| "Processed": false
| },
| {
| "UID": "00000000-0000-0000-0000-000000000000",
| "Date": "2022-11-24T00:00:00",
| "Hours": 8.000000,
| "Processed": false
| },
| {
| "UID": "00000000-0000-0000-0000-000000000000",
| "Date": "2022-11-25T00:00:00",
| "Hours": 8.000000,
| "Processed": false
| },
| {
| "UID": "00000000-0000-0000-0000-000000000000",
| "Date": "2022-11-26T00:00:00",
| "Hours": 0.000000,
| "Processed": false
| },
| {
| "UID": "00000000-0000-0000-0000-000000000000",
| "Date": "2022-11-28T00:00:00",
| "Hours": 8.000000,
| "Processed": false
| },
| {
| "UID": "00000000-0000-0000-0000-000000000000",
| "Date": "2022-11-29T00:00:00",
| "Hours": 0.000000,
| "Processed": false
| }
| ]
| }
| ],
| "URI": "https://arl2.api.myob.com/accountright/dcc6be7f-6e9e-4c5e-b14d-470eXXXXXXX/Payroll/Timesheet/974c9258-90dd-462f-8463-c81022b47504?StartDate=2022-11-23T00:00:00&EndDate=2022-11-29T00:00:00"
| }

Screenshot of the timesheet from the UI:

The response headers sends back the location filed with the below URL:

location: {domain}/{cf guid}/Payroll/Timesheet/974c9258-90dd-462f-8463-c81022b47504?StartDate=2022-11-23T00:00:00&EndDate=2022-11-29T00:00:00

{domain}is defined as: https://api.myob.com/accountright/
{cf guid}is defined as the company file guide.

Please note: that both StartDate&EndDate are passed back, this is needed to update the existing timesheet. So far you can see right away the behaviour differs from that of other endpoints. Essentially PUT  is used to insert, delete as well as update existing timesheet entries.

The GET operator is still used to retrieve timesheet records. Please note: when querying for a timesheet that sits outside the current StardDate/EndDate period you’ll need to use the uri structure to access.

Updating an existing Timesheet

When updating a timesheet you will need to pass the Employee.UID for the update on the url but the StartDate&EndDate fields are also required to define the range. 

Method: PUT

Endpoint example: {domain}/{cf guid}/Payroll/Timesheet/974c9258-90dd-462f-8463-c81022b47504?StartDate=2022-11-23T00:00:00&EndDate=2022-11-29T00:00:00

The update operation removes the old existing entries from the date range set and adds new ones in its place, overwriting the collection of what was previously there.

How to delete a Timesheet

In order to delete a timesheet, once again PUT is needed here. Just like the update above, you’ll also need to include the Employee.UID, StartDate&EndDate on the url. The JSON body of the request requires all 3 of these fields.

{domain}/{cf guid}/Payroll/Timesheet/974c9258-90dd-462f-8463-c81022b47504?StartDate=2022-11-23T00:00:00&EndDate=2022-11-29T00:00:00

Update the values to 0 and this will in turn remove the values and effectively delete the timesheet.

Please note: when updating or deleting existing timesheet entries, ensure it has not already been processed as part of a payroll run. The Processed Boolean field inside the Entries array can tell you if it has or not when retrieving.

If you have any questions, feel to log a ticket with the Customisation & Integration Team.