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.
There are two methods for generating credentials for the API:
- While logged into Timesheets.com as the Primary Administrator navigate to ‘Tools’ from the left menu.
- From the ‘Tools’ menu navigate to ‘Generate API Keys’.
- Use the ‘Generate Credentials’ button to generate an API key and authorization token. The result will also contain the header name and value pairs.
- Use the /auth/token endpoint from the Taffy dashboard (or any other method you’d like)
- Post your Timesheets.com primary administrator username and password. If the account is active and in good standing, a response with the API key, token, and header name values will be returned.
Once an API key and authorization token have been created, send the following headers with your request:
The header names shown here may be different than those returned in the response when creating credentials. Use the names provided in the response.
For any further requests in Taffy: open the endpoint, click Add Header, paste the header in, configure your request and send it.
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:
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.