Tips and Suggestions

Last Updated: November 07, 2016

Requesting items that have changed since you last made a request to the API

When you are looking to see whether any items have changed since your last request, it is best to query the last_modified_timestamps API endpoint. This will allow you to easily make a single API query and see the most recent time any object from an endpoint was modified.

Working with Jobcodes & Jobcode Assignments

When working with Jobcodes it is highly recommended to use the Jobcode Assignments endpoint whenever possible in order to limit the number of jobcodes returned from a request. This becomes very important when dealing with TSheets accounts connected with external services such as Quickbooks since it is likely that the account will have a large number of Jobcodes.

Archiving objects no longer in use

To keep your account running as efficiently as possible, it is a good idea to archive certain objects once you are done with them. You can archive Users, Jobcodes, and Customfielditems when they're no longer actively being used. You do this by setting their 'active' field to false. All of these items are still represented in reports, even though they're archived.

You cannot archive timesheets. If you delete a timesheet, it is permanently removed. To retain the ability to perform historical reporting on time, we recommend that you do NOT delete timesheets - unless it's for the purpose of correcting an inaccuracy.

Handling Supplemental Timesheet Data

When fetching timesheets via TSheets, supplemental data that is pertinent to the timesheets returned will be sent back in a "supplemental_data" JSON object unless you exclude it with an API filter. Within this object you will find additional objects related to the timesheets that were returned in the result set. In the example below, Jobcode, User, and Custom Field objects are returned if they are referenced in the timesheet results. This is done specifically to esure that API consumers have all the necessary data to display any timesheets that are returned. Knowing this, it is a best practice for API consumers to always parse and store any supplemental data should they wish to persist and display these timesheets later (for offline viewing, etc).

You can exclude supplemental data from GET requests for the timesheets and other endpoints by including the parameter "supplemental_data" with a value of "no" (supplemental_data=no). If your application will not be using the supplemental data from a given request, you can include this parameter to reduce payload size and improve the response time.

Example Request:

curl -H "Authorization: Bearer " -i "https://api.tsheets.com/api/v1/timesheets?start_date=12-05-2010&end_date=12-05-2013"

Response:

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

{
 "results": {
  "timesheets": {
   "142835829": {
    "id": 142835829,
    "user_id": 1396641,
    "jobcode_id": 20355120,
    "start": "2013-07-23T10:00:00-07:00",
    "end": "2013-07-23T13:10:23-07:00",
    "duration": 11423,
    "date": "2013-07-23",
    "tz": -7,
    "tz_str": "",
    "type": "regular",
    "location": "TSheets API Tester",
    "active": "0",
    "locked": 0,
    "notes": "This is a test of the emergency broadcast system",
    "customfields": {
     "24068": "",
     "24066": ""
    },
    "last_modified": "2013-12-13T22:52:08+00:00"
   },
   "142835831": {
    "id": 142835831,
    "user_id": 1396641,
    "jobcode_id": 20347779,
    "start": "2013-07-25T09:30:00-07:00",
    "end": "2013-07-25T13:10:23-07:00",
    "duration": 13223,
    "date": "2013-07-25",
    "tz": -7,
    "tz_str": "",
    "type": "regular",
    "location": "TSheets API Tester",
    "active": "0",
    "locked": 0,
    "notes": "This is a test",
    "customfields": {
     "24068": "",
     "24066": ""
    },
    "last_modified": "2013-12-13T20:30:42+00:00"
   }
  }
 },
 "more": false,
 "supplemental_data": {
  "jobcodes": {
   "20355120": {
    "id": 20355120,
    "parent_id": 0,
    "assigned_to_all": true,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "",
    "name": "Another Jobcode",
    "last_modified": "2013-12-13T22:16:18+00:00",
    "created": "2013-12-13T22:16:18+00:00",
    "required_customfields": [
     
    ],
    "filtered_customfielditems": ""
   },
   "20347779": {
    "id": 20347779,
    "parent_id": 0,
    "assigned_to_all": true,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "",
    "name": "Global Jobcode",
    "last_modified": "2013-12-12T23:53:31+00:00",
    "created": "2013-12-12T23:53:31+00:00",
    "required_customfields": [
     
    ],
    "filtered_customfielditems": ""
   }
  },
  "users": {
   "1396641": {
    "id": 1396641,
    "first_name": "API",
    "last_name": "Employee",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "apiemployee",
    "email": "",
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "last_modified": "2013-12-12T18:58:13+00:00",
    "last_active": "2013-12-13T22:52:08+00:00",
    "created": "2013-12-12T18:58:13+00:00",
    "client_url": "tsheetsapitester",
    "mobile_number": "",
    "approved_to": "",
    "submitted_to": ""
   }
  },
  "customfields": {
   "24068": {
    "id": 24068,
    "required": false,
    "applies_to": "timesheet",
    "type": "free-form",
    "short_code": "ffcf1",
    "regex_filter": "",
    "name": "Free-form Custom Field 1",
    "last_modified": "2013-12-13T18:18:57+00:00",
    "created": "2013-12-13T18:18:57+00:00",
    "ui_preference": "text_box_with_suggest",
    "required_customfields": [
     
    ]
   },
   "24066": {
    "id": 24066,
    "required": false,
    "applies_to": "timesheet",
    "type": "managed-list",
    "short_code": "mlcf1",
    "regex_filter": "",
    "name": "Managed List Custom Field 1",
    "last_modified": "2013-12-13T18:18:36+00:00",
    "created": "2013-12-13T18:18:36+00:00",
    "ui_preference": "drop_down",
    "required_customfields": [
     
    ]
   }
  }
 }
}