REST API: Edit Timesheets

Last Updated: April 24, 2017

Description

Edit one or more timesheets in your company. We will handle batches of up to 50 timesheets at a time. More than 50 timesheets will result in a 413 - Request entity too large error.

Resource Information

HTTP Method PUT
Endpoint https://rest.tsheets.com/api/v1/timesheets
Authentication Token header required. See authentication section
Request format json object. Pass an array of timesheet objects as the value to a 'data' property (see example below).
Response format json
Response object Timesheet

Timesheet properties

When editing a timesheet, you must uniquely identify the timesheet by passing in its id. All other properties defined on a below may be passed in to the request with a new value in order to change it. If the value passed in is the same as it was previously, or if a particular property is not passed in at all, it will be ignored.

Manual Timesheets

duration:
optional
Integer. Number of seconds that you'd like to record against this manual timesheet. Will get converted to hours, rounded to the nearest 2 decimal places when the timesheet is saved.
date:
optional
String. YYYY-MM-DD formatted date string. Date you'd like the manual timesheet recorded against.

Regular Timesheets

start:
optional
String (ISO8601 format). Start time of the timesheet. Time should reflect the user's local time (i.e. 2013-02-12T15:19:21-07:00).
end:
optional
String (ISO8601 format). End time of the timesheet. Time should reflect the user's local time (i.e. 2013-02-12T15:19:21-07:00). Enter an empty string to make the timesheet active.

Both

id:
required
Integer. Timesheet id of the timesheet that you are going to edit.
jobcode_id:
optional
Integer. Jobcode id that you'd like this timesheet to be recorded against.
notes:
optional
String. Notes you'd like associated with this timesheet.
customfields:
optional
JSON object. Only present if the Advanced Tracking Add-on is installed. This is a key / value map of customfield ids to the customfield items that are associated with the timesheet.

Status Codes

Each timesheet that is edited will come back with a _status_code and _status_message that will indicate whether the timesheet was edited successfully. If there was a problem editing a timesheet, there may also be an additional field, _status_extra, which will contain more details about the failure.

_status_code Meaning
200 OK. Timesheet was edited successfully.
201 Fulfilled. Timesheet was created successfully. Other timesheets may have been modified as a result (i.e. due to timesheet splits or an automatic Lunch Break). Be sure to process entries for timesheets or timesheets_deleted in the supplemental_data portion of the response.
404 Not Found. Timesheet either has never existed or has been deleted.
409 Conflict. Because a conflict would have resulted in the change requested, the timesheet was not modified. The unmodified timesheet's properties will be included in the response, to make it easy to revert to the unmodified version of the timesheet.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this timesheet. See the _status_extra value for more detail.

Examples

Change some information for each of these timesheets.
Note: The code example below references user ids and jobcode ids that will need to be substitued with ids associated with your TSheets account.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -H "Content-Type: application/json" -X PUT -i "https://rest.tsheets.com/api/v1/timesheets" -d @tstimesheet_edit.json

## contents of the tstimesheet_edit.json file are:
{
 "data":
  [
    {
     "id":136022168,
     "end":"2013-08-08T14:00:00-07:00",
     "jobcode_id":"18081060"
    },
    {
     "id":136022240,
     "date":"2013-08-08",
     "duration":15552
    }
  ]
}



## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
 "results": {
  "timesheets": {
   "1": {
    "_status_code": 200,
    "_status_message": "Updated",
    "id": 136022168,
    "user_id": 1242509,
    "jobcode_id": 18081060,
    "start": "2013-08-08T09:00:00-06:00",
    "end": "2013-08-08T15:00:00-06:00",
    "duration": 21600,
    "date": "2013-08-08",
    "tz": -7,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "active": "0",
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "",
     "19144": ""
    },
    "last_modified": "2013-08-09T21:30:10+00:00"
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Updated",
    "id": 136022240,
    "user_id": 1242515,
    "jobcode_id": 0,
    "start": "2013-08-08T08:00:00-06:00",
    "end": "2013-08-08T12:19:12-06:00",
    "duration": 15552,
    "date": "2013-08-08",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "manual",
    "location": "(Eagle, ID?)",
    "active": "0",
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "",
     "19144": ""
    },
    "last_modified": "2013-08-09T21:30:12+00:00"
   }
  }
 },
 "supplemental_data": {
  "jobcodes": {
   "18081060": {
    "id": 18081060,
    "parent_id": 0,
    "assigned_to_all": true,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "test",
    "name": "Test",
    "last_modified": "2013-07-24T18:18:36+00:00",
    "created": "2013-07-23T22:41:02+00:00"
   }
  },
  "users": {
   "1242509": {
    "id": 1242509,
    "first_name": "Courtney",
    "last_name": "Ballenger",
    "group_id": 144961,
    "active": true,
    "employee_number": 1,
    "salaried": false,
    "exempt": false,
    "username": "cballenger",
    "email": "garrett@tsheets.com",
    "payroll_id": "1",
    "hire_date": "2013-05-28",
    "term_date": "0000-00-00",
    "job_title": "",
    "gender": "",
    "last_modified": "2013-07-12T15:52:36+00:00",
    "last_active": "2013-08-09T21:30:10+00:00",
    "created": "2013-05-28T20:14:53+00:00",
    "mobile_number": ""
   },
   "1242515": {
    "id": 1242515,
    "first_name": "Alexander",
    "last_name": "Luzzana",
    "group_id": 144959,
    "active": true,
    "employee_number": 4,
    "salaried": true,
    "exempt": false,
    "username": "aluzzana",
    "email": "garrett@tsheets.com",
    "payroll_id": "4",
    "hire_date": "2012-07-01",
    "term_date": "0000-00-00",
    "job_title": "",
    "gender": "",
    "last_modified": "2013-07-12T15:52:00+00:00",
    "last_active": "2013-08-09T17:30:41+00:00",
    "created": "2013-05-28T20:23:44+00:00",
    "mobile_number": ""
   }
  },
  "customfields": {
   "19142": {
    "id": 19142,
    "required": false,
    "type": "timesheet",
    "ui_preference": "managed-list",
    "short_code": "cf1",
    "regex_filter": "",
    "name": "Custom Field 1",
    "last_modified": "2013-07-26T18:58:23+00:00",
    "created": "2013-07-23T23:09:14+00:00"
   },
   "19144": {
    "id": 19144,
    "required": false,
    "type": "timesheet",
    "ui_preference": "managed-list",
    "short_code": "cf2",
    "regex_filter": "",
    "name": "Custom Field 2",
    "last_modified": "2013-07-26T18:58:32+00:00",
    "created": "2013-07-23T23:09:32+00:00"
   }
  }
 }
}