TSheets REST API

Last Updated: September 24, 2015

Introduction

The TSheets API (Application Programming Interface) is based on REST principles. It's very easy to write and test applications. You can use your browser to access URLs, and you can use pretty much any TLS-capable HTTP client in any programming language to interact with the API. The API allows you to query meta-data about your account, users, jobcodes, timesheets, GPS points, and custom fields. You can also create timesheets, users, jobcodes, etc.

All access to the API occurs over an TLS-encrypted secure channel, so your API client must support TLS. To ensure data privacy, unencrypted HTTP is not supported.

Base URL

All URLs referenced in the documentation have the following base:

https://rest.tsheets.com/api/v1
        

Request Throttling

To prevent abuse of the TSheets API, we limit requests to a maximum number (currently 300) within a given time window (currently 10 minutes). Rate limiting is primarily considered on a per-connection basis (per access token). If you exceed the current rate limit, you will receive a 429 'Too many requests' response from our API. You will continue to receive a 429 response until you're out of the current time window. The threshold and time window may adjust dynamically to lower values if you are found to be abusing the system. These thresholds are subject to change - we'll keep this page updated if/when any changes are made.

Helper Libraries

This documentation explains the format for raw HTTP(S) calls to the TSheets API. Helper libraries are also available upon request in a number of popular programming languages, which make it easy for you to get started with TSheets.

While a helper library can make it easier to consume the API, it is certainly not necessary and the API is still very straight-forward to use even without one. Simply use a built-in http class or library for your language of choice.

Partnership Requests and Information

By default we allow you to connect to 3 additional client accounts (besides your own) via your API application keys. If you are building an integration and are interested in enabling your application for use by any TSheets customer, please fill out the form at the bottom of our partnerships page and we can help guide you through our simple integration process.

Here are a few of the things we'll be looking for before allowing your application access to our other TSheets customers:

  • Are you obtaining tokens by directing the user through our OAuth flow?
  • Are you storing the API App client_id and client_secret encrypted?
  • Are you storing OAuth tokens encrypted?
  • Do you have a mechanism in place for refreshing OAuth tokens before they expire - to prevent people from needing to log in again?
  • If you are unable to refresh the token, what is the user experience for logging in and renewing it?
  • What permissions are required for your app to do its work? Are you checking those permissions for the user tied to the OAuth token - and not just assuming you'll have it?
  • When checking for changes to data, are you using the last_modified_timestamps endpoint?
  • How are changes to data being checked from your app? Polling? Manually? Both? If you're polling, how often?
  • If client doesn't have a TSheets account, are you utilizing the account creation mechanism available via the OAuth flow?
  • On initial sync, are you getting all data? On subsequent syncs, are you utilizing last_modified times to pull data?
  • When editing or creating multiple objects, are you doing so via batch operations (i.e. up to 50 with one request vs. a separate request for each)?

Getting Help

If you encounter any problems consuming the API or have suggestions please feel free to contact us at help@tsheets.com

Version History

Current version: 1.0