Timesheets.com now offers an API for customer use.

API Dashboard:

https://secure.timesheets.com/api/public/v1/index.cfm

Current documentation version:

• 1.0.1

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.
• keys/tokens do not expire but can be deleted. It’s good practice to delete old/out of date information.

There are two methods for generating credentials for the API:

1. While logged into Timesheets.com as the Primary Administrator navigate to ‘Tools’ from the left menu.
2. From the ‘Tools’ menu navigate to ‘Generate API Keys’.
3. Use the ‘Generate Credentials’ button to generate an API key and authorization token. The result will also contain the header name and value pairs.

OR

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, 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:

apikey: [apikey]
x-ts-authorization: [token]

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.

The base URL in your script should be: 

https://secure.timesheets.com/api/public/v1/

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.

Error Keys

The code values and their keys can be pulled from the /server/constants API endpoint. This will return the name of the error/warning (e.g. PAYROLL_CODE_LOCKED = 2)

Code	Description
PAYROLL_CODE_PROCESSED = “0”	Payroll was successfully processed The payroll report was generated as a summary only and does not include any time records
PAYROLL_CODE_SUMMARY_ONLY = “1”	The payroll report was generated as a summary only and does not include any time records
PAYROLL_CODE_LOCKED = “2”	Payroll report is locked and cannot be processed by current user
PAYROLL_CODE_INVALID_DATES = “3”	The payroll report contains invalid run dates
PAYROLL_CODE_NO_RECORDS_FOUND = “4”	There were no valid records in the payroll dates
PAYROLL_CODE_OVERLAPPING_PERIODS = “5”	Users included in the payroll overlap existing payroll periods
PAYROLL_CODE_OVERLAPPING_RECORDS = “6”	Users included in the payroll have overlapping records
PAYROLL_CODE_ALERTS_EXIST = “7”	Alerts exist on records included in the payroll report
PAYROLL_CODE_PROCESS_VALIDATION_ERROR = “8”	There was an error when attempting to validate the payroll records to process
PAYROLL_CODE_PROCESS_VALIDATION_FAILED = “9”	Underlying records in the payroll report have been modified
PAYROLL_CODE_DUPLICATE_USERS_FOUND = “10”	Duplicate UserIDs were detected in the payroll report
PAYROLL_CODE_NO_USERS_INCLUDED = “11”	No users were included in the report
PAYROLL_CODE_UNPAID_RECORDS_EXISTS = “12”	Unpaid records exist before the payroll date
PAYROLL_CODE_STANDARD_SPLITPAID_RECORDS_EXISTS = “13”	Standard split paid records exist in the payroll report
PAYROLL_CODE_SALARIED_SPLITPAID_RECORDS_EXISTS = “14”	Salaried split paid records exist in the payroll report
PAYROLL_CODE_INVALID_RUNBYID = “15”	The user attempting to run the payroll is not authorized or valid
PAYROLL_CODE_INVALID_APPEND_PAYROLLID = “16”	Attempt to append to an invalid payroll
PAYROLL_CODE_USERS_ALREADY_EXIST_IN_PAYROLL = “17”	Attempt to add users to a payroll report they already exist in
PAYROLL_CODE_USERS_HAVE_POSTDATED_PAYROLL = “18”	Attempt to add users to a payroll report already exist in a post dated payroll
PAYROLL_CODE_INVALID_PAYROLLID = “19”	Payroll ID was not valid
PAYROLL_CODE_INVALID_PARTIAL_USER_DELETE = “20”	The list of partial users to delete was not valid for the payroll period
PAYROLL_CODE_INVALID_TIMEZONE_FOR_PERIOD = “21”	There were multiple time zones detected in the payroll period for a single user
PAYROLL_CODE_NONSEQUENTIAL_RECORDS = “22”	Non-sequential records were detected while running payroll
PAYROLL_CODE_INVALID_ACCRUAL_SETTINGS_FOR_USER = “23”	There was one or more users with invalid accrual by hours worked settings
PAYROLL_CODE_RECORDS_EXCEED_MAX_THRESHOLD = “24”	Records in the payroll report were identified as exceeding the specified max threshold