REST API: Add Timesheets

Last Updated: July 17, 2015

Description

Add one or more timesheets to 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 POST
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

Required Manual Timesheet Properties

type:
String. Always 'manual' for a manual timesheet.
duration:
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:
String. YYYY-MM-DD formatted date string. Date you'd like the manual timesheet recorded against.

Required Regular Timesheet Properties

type:
String. Always 'regular' for a regular timesheet.
start:
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:
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.

Required Timesheet Properties (Both Manual & Regular)

user_id:
Integer. User id that this timesheet will be recorded against.
jobcode_id:
Integer. Jobcode id that you'd like this timesheet to be recorded against.

Optional Timesheet Properties

For a full list of the properties that may be set on a timesheet, see the Timesheet object.

Status Codes

Each timesheet that is created will come back with a _status_code and _status_message that will indicate whether the timesheet was created successfully. If there was a problem creating 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 created 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.
406 Not Acceptable. Conflict exists with another timesheet. See the _status_extra value for more detail.
417 Expectation Failed. Something was wrong or missing with the properties supplied for this timesheet. See the _status_extra value for more detail.

Examples

Create three new timesheets (one manual and two regular). Two succeed. The third fails because of an overlap with an existing timesheet.
Note: The code example below references user ids, jobcode ids, and custom fields that will need to be substitued with ids associated with your TSheets account.

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

## contents of the tstimesheets_create.json file are:
{
 "data":
  [
    {
     "user_id":1242515,
     "type":"regular",
     "start":"2013-07-23T10:00:00-07:00",
     "end":"2013-07-23T13:10:23-07:00",
     "jobcode_id":"17288283",
     "notes":"This is a test of the emergency broadcast system",
     "customfields": {
      "19142":"Item 1",
      "19144":"Item 2"
     }
    },
    {
     "user_id":1242515,
     "type":"regular",
     "start":"2013-07-25T09:30:00-07:00",
     "end":"2013-07-25T13:10:23-07:00",
     "jobcode_id":"17288283",
     "notes":"This is a test",
     "customfields": {
      "19142":"Item 1",
      "19144":"Item 2"
     }
    },
    {
     "user_id":1242515,
     "type":"manual",
     "date":"2013-07-23",
     "duration":"15552",
     "jobcode_id":"17288283",
     "notes":"This is a test of a manual time entry",
     "customfields": {
      "19142":"Item 1",
      "19144":"Item 2"
     }
    }
  ]
}



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

{
 "results": {
  "timesheets": {
   "1": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 135653104,
    "user_id": 1242515,
    "jobcode_id": 17288283,
    "start": "2013-07-23T11:00:00-06:00",
    "end": "2013-07-23T14:10:23-06:00",
    "duration": 11423,
    "date": "2013-07-23",
    "tz": -7,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "active": "0",
    "locked": 0,
    "notes": "This is a test of the emergency broadcast system",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "2": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 135653106,
    "user_id": 1242515,
    "jobcode_id": 17288283,
    "start": "2013-07-25T10:30:00-06:00",
    "end": "2013-07-25T14:10:23-06:00",
    "duration": 13223,
    "date": "2013-07-25",
    "tz": -7,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "active": "0",
    "locked": 0,
    "notes": "This is a test",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "3": {
    "_status_code": 200,
    "_status_message": "Created",
    "id": 135653108,
    "user_id": 1242515,
    "jobcode_id": 17288283,
    "start": "2013-07-23T08:00:00-06:00",
    "end": "2013-07-23T12:19:12-06:00",
    "duration": 15552,
    "date": "2013-07-23",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "manual",
    "location": "(Eagle, ID?)",
    "active": "0",
    "locked": 0,
    "notes": "This is a test of a manual time entry",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   }
  }
 },
 "supplemental_data": {
  "jobcodes": {
   "17288283": {
    "id": 17288283,
    "parent_id": 0,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "dev",
    "name": "Development Team",
    "last_modified": "2013-07-24T19:05:53+00:00",
    "created": "2013-05-28T20:19:33+00:00"
   }
  },
  "users": {
   "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-01T22:17:47+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"
   }
  }
 }
}