REST API: List Timesheets

Last Updated: February 21, 2017

Description

Retrieves a list of all timesheets associated with your company, with filters to narrow down the results.

Resource Information

HTTP Method GET
Endpoint https://rest.tsheets.com/api/v1/timesheets
Authentication Token header required. See authentication section
Request format Everything is handled through the request uri on a GET.
Response format json
Response object Timesheet

Available Filters

ids:
required - unless modified_before, modified_since, or start_date are set
Integer. Comma separated list of one or more timesheet ids you'd like to filter on. Only timesheets with an id set to one of these values will be returned. If omitted, all timesheets matching other specified filters are returned.
start_date:
required - unless modified_before, modified_since, or ids is set
String. YYYY-MM-DD formatted date. Any timesheets with a date falling on or after this date will be returned.
end_date:
String. YYYY-MM-DD formatted date. Any timesheets with a date falling on or before this date will be returned.
jobcode_ids:
optional
Integer. A comma-separated string of jobcode ids. Only time recorded against these jobcodes or one of their children will be returned.
user_ids:
optional
Integer. A comma-separated list of user ids. Only timesheets linked to these users will be returned.
group_ids:
optional
Integer. A comma-separated list of group ids. Only timesheets linked to users from these groups will be returned.
on_the_clock:
optional
String. 'yes', 'no', or 'both'. Default is 'no'. If a timesheet is on_the_clock, it means the user is currently working (has not clocked out yet).
jobcode_type:
optional
String. 'regular', 'pto', 'paid_break', 'unpaid_break', or 'all'. Default is 'all'. Only timesheets linked to a jobcode of the given type are returned.
modified_before:
required - unless modified_since, ids, or start_date are set
String (ISO8601 format). Only timesheets modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
required - unless modified_before, ids, or start_date are set
String (ISO8601 format). Only timesheets modified since this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
supplemental_data:
optional
String. 'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
per_page:
optional
Integer. Represents how many results you'd like to retrieve per request (page). Default is 50. Max is 50.
page:
optional
Integer. Represents the page of results you'd like to retrieve. Default is 1.

Examples

Retrieve a list of on_the_clock and not on_the_clock timesheets from the last 10 days.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/timesheets?start_date=2013-07-15&end_date=2013-07-25&on_the_clock=both"

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

{
 "results": {
  "timesheets": {
   "135288482": {
    "id": 135288482,
    "user_id": 1242515,
    "jobcode_id": 17288283,
    "start": "2013-07-16T09:04:00-06:00",
    "end": "2013-07-16T15:57:00-06:00",
    "duration": 24780,
    "date": "2013-07-16",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock": false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135288514": {
    "id": 135288514,
    "user_id": 1242509,
    "jobcode_id": 18080900,
    "start": "2013-07-16T13:07:00-06:00",
    "end": "2013-07-16T17:29:00-06:00",
    "duration": 15720,
    "date": "2013-07-16",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock", false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135288460": {
    "id": 135288460,
    "user_id": 1242509,
    "jobcode_id": 18080900,
    "start": "2013-07-18T08:09:00-06:00",
    "end": "2013-07-18T14:58:00-06:00",
    "duration": 24540,
    "date": "2013-07-18",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock", false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135288162": {
    "id": 135288162,
    "user_id": 1242515,
    "jobcode_id": 17288283,
    "start": "2013-07-19T12:06:00-06:00",
    "end": "2013-07-19T14:59:00-06:00",
    "duration": 10380,
    "date": "2013-07-19",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock", false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135288102": {
    "id": 135288102,
    "user_id": 1242515,
    "jobcode_id": 17288283,
    "start": "2013-07-22T13:05:00-06:00",
    "end": "2013-07-22T18:07:00-06:00",
    "duration": 18120,
    "date": "2013-07-22",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock", false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135522568": {
    "id": 135522568,
    "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?)",
    "on_the_clock", false,
    "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"
   },
   "135366264": {
    "id": 135366264,
    "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?)",
    "on_the_clock", false,
    "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"
   },
   "135288084": {
    "id": 135288084,
    "user_id": 1242509,
    "jobcode_id": 18080900,
    "start": "2013-07-23T09:07:00-06:00",
    "end": "2013-07-23T15:02:00-06:00",
    "duration": 21300,
    "date": "2013-07-23",
    "tz": -6,
    "tz_str": "tsMT",
    "type": "regular",
    "location": "(Eagle, ID?)",
    "on_the_clock", false,
    "locked": 0,
    "notes": "",
    "customfields": {
     "19142": "Item 1",
     "19144": "Item 2"
    },
    "last_modified": "1970-01-01T00:00:00+00:00",
    "created": "1970-01-01T00:00:00+00:00"
   },
   "135366260": {
    "id": 135366260,
    "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?)",
    "on_the_clock", false,
    "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"
   },
   "135366262": {
    "id": 135366262,
    "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?)",
    "on_the_clock", false,
    "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"
   }
  }
 },
 "more": false,
 "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"
   },
   "18080900": {
    "id": 18080900,
    "parent_id": 17288279,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "",
    "name": "Customer10",
    "last_modified": "2013-07-23T22:31:28+00:00",
    "created": "2013-07-23T22:31:28+00:00"
   },
   "17288279": {
    "id": 17288279,
    "parent_id": 0,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": true,
    "billable_rate": 0,
    "short_code": "asm",
    "name": "Assembly Line",
    "last_modified": "2013-07-24T19:05:46+00:00",
    "created": "2013-05-28T20:18:17+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-07-30T20:06:13+00:00",
    "created": "2013-05-28T20:23:44+00:00",
    "mobile_number": ""
   },
   "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-07-25T17:13:06+00:00",
    "created": "2013-05-28T20:14:53+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"
   }
  }
 }
}
    

Retrieve a list of all timesheets within a certain date range which were recorded against jobcode id 235494. Set pagination to 10 results/page.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/timesheets?start_date=2013-01-01&end_date=2013-01-31&on_the_clock=no&jobcode_ids=235494&per_page=10"

## RESPONSE (shortened for readability)
## (response would have the same layout as the above example)
    

Retrieve a list of timesheets with ids 12, 367, and 3489.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/timesheets?ids=12,367,3489"

## RESPONSE
## (response would have the same layout as the above example)
    

Retrieve page 3 of a list of timesheets linked to user with id 1123 within a given time range.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/timesheets?page=3&user_ids=1123&start_date=2013-01-01&end_date=2013-02-01"

## RESPONSE
## (response would have the same layout as the above example)
    

Retrieve a list of timesheets that have been modified since Jan 1, 2013

## REQUEST
## Note that instead of a plus, we're using '%2B', the url-encoded equivalent - to prevent the + getting replaced by a space.
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/timesheets?modified_since=2013-01-01T00:00:00%2B00:00"

## RESPONSE
## (response would have the same layout as the above example)