Getting Started with the API

Timesheets.com now offers an API for customer use. You can click here to access the first alpha version.

There are a few things to keep in mind when making use of the API:

  • All requests require a header with an API key and an authorization token. The authorization token authenticates you as a specific user from your Timesheets.com account.
  • Currently, only the Primary Administrator is authorized to generate API credentials for themselves. This is to simplify the security of the API and requests sent to it.
  • Too many failed authentication attempts for a token will result in a timed lockout of further requests. The API in general is rate-limited to a rolling five requests per sixty seconds to any specific API key.
  • Important: Treat your keys/tokens like passwords and keep them secret. When working with the API, use keys/tokens as environment variables instead of hardcoding them into your programs.

To generate credentials for the API:

  1. Use the /auth/token endpoint from the Taffy dashboard (or any other method you’d like)
  2. Post your Timesheets.com primary administrator username and password. If the account is active and in good standing, an API key and token will be returned.
  3. Create an http header from this data:

apikey: [apikey]
authorization: bearer [token]

For any further requests in Taffy: open the endpoint, click Add Header, paste the header in, configure your request and send it.

Regarding Requests

In order to keep the API simple for data consumption, complex response and error codes have been omitted. All requests which authenticate successfully will return a 200 response. The response itself will indicate errors or the data requested.

Most endpoints will return a JSON struct as follows:

{
errors: [],
data: []
}

If any errors were detected in the request (such as missing or invalid parameters) the errors key will contain a list of plain English messages. For the most part, these are the same UI error messages you’d see using the application itself. If the errors array is empty, the data key will contain the requested data. This can and will vary based on the endpoint.

All query data is returned in column format with a column key listed the fields in order, and a data key with the corresponding data.

Note: Some keys may be returned all uppercase and some may be camelcase. This is due to idiosyncrasies in automatic data marshaling within the application framework we’re built on.

Was this article helpful?

Related Articles