API

This page is part of the TSheets User Guide

The TSheets API enables your website or application to integrate with TSheets Time Tracking software.

Overview

Getting Started

• First you'll need to get an API key. Login to your TSheets account and click Company Settings, then Add-ons and then install the API add-on. A box will open and display your new API key.
• Each TSheets account has a unique "Access URL" (or "Client URL"). You'll use your own as you develop your application. All the examples here use ‘demo.tsheets.com’.
• Don't reinvent the wheel if you don't need to! Check out the API toolkits in the Downloads section.

What You Should Know

• TSheets.com uses a REST interface for our API. REST is a simple format that allows you to make queries by constructing a URI containing variables and values and submitting to our API web page. The server responds with XML or JSON output containing the information that you requested.
• Each API request is composed of two parts. An action and variables for that action. Additionally, all API calls (with the exception of get_token) require a token parameter that proves you are logged in. Normally you won't have to worry about this though, since our PHP class handles authentication for you.
• All API output is returned in XML format unless you add the output_format=json option to your requests. (Note that our PHP class returns all data in JSON by default.) All API requests will include a status field with a value of either ‘ok’ or ‘fail’. If the status is 'ok' there will also be a field named ‘message’ with more details. If the status is 'fail' there will also be an element named 'last_error' with more details.
• We recommend using HTTPS for all API requests to your Access URL
• GET vs. POST. Our API reads your actions and parameters from both GET and POST data. While examples below show parameters being posted via GET, it will work equally well if some (or all) of the parameters are passed as POST data.

Downloads

PHP API Toolkit

Download the TSheets API Toolkit and you'll have your application talking with our servers in 30 seconds. Simply extract and point your browser to http://www.YOURURL.com/tsheets/samples/ to see the API in action. Edit the samples/config.inc.php to connect the samples to your own account. Include tsheets.inc.php in your application when ready to start developing your own time tracking tools!

Download: tsheets-api-toolkit-php-v1.00.zip (9kb Jul 11th, 2010)

Try the Toolkit Samples: http://apisamples.tsheets.com/samples/

Perl API Toolkit

A Perl class for accessing the TSheets API. Time tracking on the command-line has never been easier! To get started just extract this package, cd into the samples/ sub-folder, and run one of the sample scripts. From there read the README.txt and start building your own application.

Download: tsheets-api-toolkit-perl-v1.02.zip (17kb Dec 9th, 2010)

API Actions

Authentication

API Toolkit Users: If you're using one of our API toolkits you don't need to worry about this section. Authentication is handled for you transparently for you :)

To start a session, your first call must pass the action ‘get_token’, and you must include your api_key:

https://demo.tsheets.com/api.php?action=get_token&api_key=12345abcdefg

In return you will get a token. Each token you receive is representative of a single TSheets user object. You must include the given token for all subsequent API calls related to that user (i.e. login, clock_in, etc.)

<result>
  <status>ok</status>
  <message>token generated successfully</message>
  <token>ff0c0144e68c1f29bb3795453862f78f</token>
</result>

Once you have obtained a token, you must call the login action to authenticate the user before calling any other actions.

To authenticate a user, use the following parameters:

• action : login
• token : Required for every API action.
• username : Username or email address associated with the target user account.
• password : Password for the given user.
• client_url : Optional. This is the client url that the user belongs to. Only set this if you're logging in as a user that belongs to an account other than your own. You'll require special permissions granted to your API key before you can use this parameter. Contact TSheets support if you require use of this parameter.

So an example would be:

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=login&username=joe&password=password

Once you log on, you will get a response indicating status of 'ok' if you were successful or a status of 'fail' if there was a problem.

<result>
  <status>ok</status>
  <message>User logged in successfully</message>
</result>

When you receive a status of 'fail' from any API action, you'll also be given an error_code, error_text, and last_error. For example:

<result>
    <status>fail</status>
    <last_error>user is not logged in, you must first perform the login action before trying other actions</last_error>
    <error_code>5002</error_code>
    <error_text>Not logged in</error_text>
</result>

• last_error => This is a detailed message describing why the failure occurred.
• error_code => This is a numeric code representing the failure that occurred. The default error_code is 9999 (generic). Please be patient with us as we work to populate these error codes with unique numbers. Please let us know if you encounter an error that you'd like to see assigned a unique error for the purposes of your application.
• error_text => This is a short description of the error_code.

---

Tracking Time

Clocking In

Usually called Clocking-in, punching the clock or starting a timer, this call lets you start tracking time for a user.

Run this action and see it's output on our API samples site! Clock-in now

Action

• clock_in

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
job_code_id	Maybe	The job-code ID that you would like to clock in with. This parameter is optional if the user has 0 or 1 job-codes assigned. Otherwise it is required.
notes		A text note to place on the timesheet. Max 2000 characters.
seconds		An integer >= 0. Treat this action as though it happened X number of seconds in the past.
username		Assumes the role of the user specified before taking action. Requires the admin or manage_timesheets permission.

Output

• The status field will either be 'ok' or 'fail'. On failure a last_error field will explain why.

Switching Job Codes

Close (clock-out of) the user's current timesheet, and clock them in again under a new job-code.

Action

• job_code_switch

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
job_code_id	Yes	The job-code ID that you would like to switch to.
notes		A text note to place on the timesheet prior to switching. Max 2000 characters.
seconds		An integer >= 0. Treat this action as though it happened X number of seconds in the past.
username		Assumes the role of the user specified before taking action. Requires the admin or manage_timesheets permission.

Output

• The status field will either be 'ok' or 'fail'. On failure a last_error field will explain why.

Timesheet Notes

Replace or append notes for the user's timesheet when they're on the clock.

Action

• replace_notes

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
notes	Yes	A text note to place on the timesheet. Max 2000 characters. Replaces existing notes by default.
append		If set to 1, the notes will get appended to the current notes, rather than overwriting them.
username		Assumes the role of the user specified before taking action. Requires the admin or manage_timesheets permission.

Output

• The status field will either be 'ok' or 'fail'. On failure a last_error field will explain why.

Clocking Out

Clock out a user. Also called punching out or stopping a timer.

Run this action and see it's output on our API samples site! Clock-out now

Action

• clock_out

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
notes		A text note to place on the timesheet prior to clocking-out. Max 2000 characters. Replaces existing notes by default.
seconds		An integer >= 0. Treat this action as though it happened X number of seconds in the past.
username		Assumes the role of the user specified before taking action. Requires the admin or manage_timesheets permission.

Output

• The status field will either be 'ok' or 'fail'. On failure a last_error field will explain why.

Adding Manual Time

This call lets you enter hours for a date and job_code for a given user.

Action

• add_manual_time

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
date	Yes	A date in the format YYYY-MM-DD when you would like the time to be recorded.
hours	Yes	A decimal >= 0.0. This value is converted to whole seconds before being stored.
job_code_id	Yes	The job-code ID that you would like to record time against. If the user has 0 job-codes assigned, use job_code_id 0.
notes		A text note to place on the timesheet. Max 2000 characters.
username		Add hours for this user. Requires the admin or manage_timesheets permission. If blank, the currently logged in user is assumed.

Output

• The status field will either be 'ok' or 'fail'. On failure a last_error field will explain why.

Deleting Time

This call lets you delete a timesheet from the system.

Action

• delete_timesheet

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
id	Yes	The id for the timesheet you would like to delete.

Output

• The status field will either be 'ok' or 'fail'. On failure a last_error field will explain why.

---

Location Information

Recording GPS Data

Record a user's current (or past) location.

Action

• gps_log

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
latitude	Yes	An angular measurement in degrees ranging from 0 deg. at the equator (low latitude) to 90 deg. at the North pole or -90 deg. at the South pole. May include up to 6 decimal places.
longitude	Yes	An angular measurement ranging from 0 deg. at the prime meridian to +180 deg. eastward and -180 deg. westward. May include up to 6 decimal places.
accuracy		A radius (in meters). Defaults to 3000.
altitude		A measurement (in meters) of vertical distance from sea-level. Defaults to zero.
activity		A keyword indicating what activity was requested in conjunction with this GPS point. Possible actions are: ci (clock-in), co (clock-out), notes (adding notes), switch (switch jobcode), none (no action - default).
seconds		An integer >= 0. Treat this action as though it happened X number of seconds in the past.
username		Assumes the role of the user specified before taking action. Requires the admin or manage_timesheets permission.

Output

• The status field will either be 'ok' or 'fail'. On failure a last_error field will explain why.

---

Read-Only Information

Retrieving Properties

If you want to retrieve a property for a user, such as clocked_in_for or who_is_working, you may do so via the “get” API action. The following parameters are available:

Run this action and see it's output on our API samples site: Run 'get' now

Action

• get

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
property	Yes	The property or properties that you would like to retrieve. You may specify multiple properties at once, just provide them separated by a pipe character ( | ), without spaces.
username	No	Retrieves information for the specified user. Only applies to the properties underneath the 'Timesheets, Day and Week Totals, Permissions' heading. You must be an admin or a manager of the given user to use this parameter. A username or user_id may be given as the value for this property.

The following properties are available for retrieval via the get action:

Account related properties

• username (username)
• fname (first name)
• lname (last name)
• company_name (company name)
• account_type (account type; i.e. personal or business)
• client_url (client URL)
• settings (settings associated with this user's account)

The following properties are returned by the settings property. A value of 1 indicates true, a 0 indicates false:

• timesheet_notes (if 1, entering notes on timesheets is allowed. A zero or blank value indicates notes are not allowed)
• hide_working_time (if 1, employees are allowed to view time worked by themselves and other employees (from the who_is_working list). A zero or blank value indicates that working times should be hidden)
• time_format (12 or 24, indicates whether to display times in military or normal format)

• tz (timezone)
• week_start (the day of the week that your company starts its week on. i.e. 'sunday'. Useful to know when figuring out a week total)

Timesheets, Day and Week Totals, Permissions

(these properties may be coupled with the 'username' parameter to get the results for a different user)

• logged_in (whether or not the user is logged in)
• clocked_in (whether or not the user is clocked in. If user is clocked_in, then output of current_jobcode is automatically given as well.)
• day_total (how much time the user has clocked for the current day)

• this will return two values: day_total - which is in HH:MM format, and day_total_seconds - which is the day total in seconds.
• if requesting day_total, you may also optionally provide the parameter 'username' and set it to another user within your company. Only someone with the admin or manage_timesheets permission may do this. Specifying username will cause the day_total to be returned for that user instead.

• week_total (shift, day and week totals)

• Returns the values for: shift_total, shift_total_seconds, day_total, day_total_seconds, week_total, week_total_seconds.

• notes (notes associated with the current timesheet)

• if requesting notes, you may also optionally provide the parameter 'username' and set it to another user within your company. Only someone with the admin or manage_timesheets permission may do this. Specifying username will cause the notes to be returned for that user instead.

• current_jobcode (the job code currently being used on the active timesheet)
• clocked_in_for (how long the user has been clocked in with the current job code)
• perms (permissions assigned to the user, 1 means they have the permission, 0 means they do not)

The following properties are returned by the perms property. A value of 1 indicates true, a 0 indicates false:

• admin (whether or not user is an admin on the account)
• mobile (whether user is able to use mobile devices to record time)
• status_box (whether user is able to get a list of who is working)
• reports (whether a user can view reports on other users' time)
• manage_timesheets (whether a user can create/edit/delete users' timesheets)
• manage_authorization (whether a user can authorize computers for use to enter time)
• manage_users (whether a user can create/edit/delete users)
• manage_my_timesheets (whether a user has the right to edit his/her own timesheet entries and create manual timesheet entries)

Other Properties

• who_is_working (a list of all employees. Those who have worked that day will also include for how long. Those who are currently working will have the 'working' property set to 1, and will have the 'job_code_id' property set to what they're currently clocked-in under)

Examples

• For example, you might want to get the properties fname, clocked_in, clocked_in_for, and day_total. Your URI would look like this:

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=get&property=clocked_in|clocked_in_for|day_total|fname

Output

• The output will be just the requested properties/attributes associated with the currently logged_on user.

<result>
  <status>ok</status>
  <message>
    successfully retrieved properties: [clocked_in|clocked_in_for|day_total|fname]
  </message>
  <clocked_in>1</clocked_in>
  <clocked_in_for>1:17</clocked_in_for>
  <day_total>1:17</day_total>
  <fname>Jared</fname>
</result>

---

Job Codes

List Job Codes

The "get_jobcodes" API action will retrieve a list of jobcodes the currently authenticated user has access to. Only jobcodes with the given parent_id will be returned. The default parent_id is 0 (top level). If the currently authenticated user is an admin or has sufficient permissions, then all jobcodes for the given parent_id will be returned. Otherwise only those assigned to the currently authenticated user (or an alternate user with the assigned_to parameter) are returned. The following parameters are available:

Action

• get_jobcodes

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
assigned_to		A username or user_id. Causes the returned list to only contain jobcodes assigned to this person. Must be an admin or have permissions to manage this user.
ids		Comma separated string of jobcode id's. Default is empty. Will only return jobcodes with these id's. When you pass a value in this parameter, 'parent_ids' is ignored and all matching records are returned, even if they have different parent_id's. If empty, all jobcodes for the given parent_ids will be returned.
parent_ids		Comma separated string of parent_id's. Default is 0. Will only return jobcodes with these parent_id's.
active		yes, no, or both. Default is yes. When yes, only returns active jobcodes. When no, only returns inactive jobcodes. When both, active and inactive jobcodes are returned.
type		regular, pto, or all. Default is all. When regular, only returns regular jobcodes. When pto, only returns pto jobcodes. When all, all jobcodes are returned.
modified_since		A UTC date-time string of the format yyyy-mm-dd hh:mm:ss. When specified, only jobcodes that have been modified since this time will be returned in the results. NOTE: When a jobcode is created, it's also considered to be modified.
modified_before		A UTC date-time string of the format yyyy-mm-dd hh:mm:ss. When specified, only jobcodes that have been modified before this time will be returned in the results. NOTE: When a jobcode is created, it's also considered to be modified.
per_page		Integer. Default is 50. Max allowed is 1000. Used to specify how many results per page you want returned.
page		Integer. Default is 1. Used to specify which page of results you want returned.

Output

• The output will be an indication of whether or not the action was successful, and any accompanying results.
• If there are more results than what is shown in the current result set, the output parameter 'more' will be set to 1. Otherwise it will be set to 0.

Add a Job Code

The "jobcode_add" API action will add a new job code. The following parameters are available:

Action

• jobcode_add

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
job_code_name	Yes	The name of the job code you'd like to add.
job_code_type		Specify 'regular' or 'pto'. Defaults to regular if this parameter is not specified.
parent_id		If 0, the new job code will be a top-level job code. Otherwise, specify the id of the job code you want as the parent.
global		Specify '1' to cause this new job code to be assigned to all employees (current and future).
assign_all		Specify '1' to cause this new job code to be added to all existing employees (new employees won't have it assigned).
billable		Specify '1' to cause this new job code to have the billable flag set.
alias		The SMS alias (short code) to be used for this job code when using text messages to clock in/out

Output

• The output will be indication of whether or not the action was successful, as well as a copy of the job code that was just added.

Edit a Job Code

The "jobcode_edit" API action will change a job code. The following parameters are available:

Action

• jobcode_edit

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
job_code_id	Yes	The id associated with the job code you want to change.
job_code_name	Yes	The new name you want to give to the job code. Either this parameter, the new_job_code_type parameter, or both, must be specified.
new_job_code_type		Specify 'regular' or 'pto'. Defaults to regular if this parameter is not specified.
parent_id		If 0, the new job code will be a top-level job code. Otherwise, specify the id of the job code you want as the parent.
global		Specify '1' to cause this new job code to be assigned to all employees (current and future).
billable		Specify '1' to cause this new job code to have the billable flag set.
alias		The SMS alias (short code) to be used for this job code when using text messages to clock in/out

Output

• The output will be indication of whether or not the action was successful, as well as a copy of the job code that was just edited.

Delete a Job Code

The "jobcode_delete" API action will delete a job code. The following parameters are available:

Action

• jobcode_delete

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
job_code_id	Yes	The id associated with the job code you want to change.

Output

• The output will be indication of whether or not the action was successful, as well as a copy of the jobcode that was just deleted.

Duplicate a Job Code

The "jobcode_duplicate" API action will duplicate a job code and all of its children. The following parameters are available:

Action

• jobcode_duplicate

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
copy_id	Yes	The id associated with the job code you want to duplicate.
duplicate_name	Yes	The new name you want to give to the duplicate job code.
parent_id	Yes	If 0, the new job code will be a top-level job code. Otherwise, specify the id of the job code you want as the parent.
alias		The SMS alias (short code) to be used for this job code when using text messages to clock in/out

Output

• The output will be indication of whether or not the action was successful, as well as a copy of the job code that was just duplicated.

Assign a Job Code to Users

The "jobcode_assign" API action will assign a job code and all of its child jobcodes (sub-jobcodes) to a user. The following parameters are available:

Action

• jobcode_assign

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
job_code_id	Yes	The id associated with the job code you want to assign.
username		The username you want to assign the job code to. If omitted, the currently logged in user is used.

Output

• The output will be indication of whether or not the action was successful.

Unassign a Job Code from Users

The "jobcode_unassign" API action will unassign a job code and all of its child jobcodes (sub-jobcodes) from a user. The following parameters are available:

Action

• jobcode_unassign

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
job_code_id	Yes	The id associated with the job code you want to unassign.
username		The username you want to unassign the job code from. If omitted, the currently logged in user is used.

Output

• The output will be indication of whether or not the action was successful.

---

User Management

Add a User

The "user_add" API action will add a new user to your account. The following parameters are available:

Action

• user_add

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
fname	Yes	First name for user.
lname	Yes	Last name for user.
username	Yes	Username for user.
passwd	Yes	Password for user.
group_id	Yes	Id of the group you want the user assigned to. This must be a numeric id obtained from the list_groups action (NOTE: list_groups action not available yet, notify support if you require this. In the meantime, you may assign a group_id of 0 to ensure that you can still create users)
email		Email address for the user
employee_id		Custom employee id associated with the user. This is usually used to store an external payroll id or something similar.
payrate		Float - represents dollar amount user earns over period stored in timeframe.
timeframe		One of hour, week, or year. Used in conjunction with payrate
permission		Name of the permission you want to assign or unassign to/from a user. List of available permissions can be obtained by calling 'get' action with property 'perms'.
perm_value		(Must be used in conjunction with parameter 'permission'. 1 or 0. 1 turns on the permission, or assigns it. 0 turns off the permission, or unassigns it.

Examples

• Adding a new user

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=user_add&fname=John&lname=Smith&passwd=testing&username=jsmith&email=jsmith@example.com&permission=mobile&perm_value=1

Output

• The output will be indication of whether or not the action was successful, as well as a copy of the user that was just added.

Edit a User

The "user_edit" API action will edit a user. The following parameters are available:

Action

• user_edit

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
username	Yes	Username for user you want to edit. If blank the currently logged on user is edited.
fname		First name for user.
lname		Last name for user.
new_username		New username you want to assign to the user.
passwd		Password for user.
group_id		Id of the group you want the user assigned to. This must be a numeric id obtained from the list_groups action (NOTE: list_groups action not available yet, notify support if you require this)
email		Email address for the user
employee_id		Custom employee id associated with the user. This is usually used to store an external payroll id or something similar.
payrate		Float - represents dollar amount user earns over period stored in timeframe.
timeframe		One of hour, week, or year. Used in conjunction with payrate
permission		Name of the permission you want to assign or unassign to/from a user. List of available permissions can be obtained by calling 'get' action with property 'perms'.
perm_value		(Must be used in conjunction with parameter 'permission'. 1 or 0. 1 turns on the permission, or assigns it. 0 turns off the permission, or unassigns it.

Examples

• Changing a password for a user

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=user_edit&passwd=testing&username=jsmith

• Changing a username and first name and last name for a user

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=user_edit&username=jsmith&new_username=johnsmith&fname=Johnny&lname=Smithy

• Setting someone up as an admin

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=user_edit&username=jsmith&permission=admin&perm_value=1

Output

• The output will be indication of whether or not the action was successful, as well as a copy of the user that was just edited.

Delete a User

The "user_delete" API action will delete a user. The following parameters are available:

Action

• user_delete

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
username	Yes	Username for user you want to delete.

Examples

• Delete a user

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=user_delete&username=jsmith

Output

• The output will be indication of whether or not the action was successful.

Reporting

Get Project Hours

Get a summary of hours by jobcode, user, and group.

Action

• get_project_hours

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
start_date	No	Report start date in YYYY-MM-DD format. If ommitted, then the date 10 years earlier than the current date is used.
end_date	No	Report end date in YYYY-MM-DD format. If ommitted, then current date is used.
job_code_id		Only hours with time against this jobcode will be returned. Output will contain a total number of hours for this jobcode, as well as a total number of hours for any jobcodes that have this job_code_id as its parent. If empty, 0 is used, and thus you'll get a total for all top-level jobcodes.
user_ids		Only hours with time recorded by one of these users will be returned. If empty, time for all users is returned.
group_ids		Only hours with time recorded by someone in one of these groups will be returned. If empty, time for all groups is returned.

Examples

• Getting a total of all top-level jobcodes, users, and groups.

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=get_project_hours

• Getting a total of all hours for jobcode id 71, and any of its immediate children.

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=get_project_hours&job_code_id=71

• Getting a total of all time spent on jobcode id 71 by group id 3442

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=get_project_hours&job_code_id=71&group_ids=3442

Output

• The output will include three top-level fields: status, message and data.
• status will either be 'ok' or 'fail'. On failure a last_error field will explain why, and the message and data fields won't be present.
• message will say something like 'Successfully retrieved hours' unless there is an error
• data will be an array of filters used, and totals. Each totals subarray will contain the object id as the key, and the total number of hours as the value.

Get Timesheets

Get a raw list of timesheets.

Run this action and see it's output on our API samples site! Run get_timesheets

Action

• get_timesheets

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
start_date	Yes	Report start date in YYYY-MM-DD format.
end_date	Yes	Report end date in YYYY-MM-DD format. Maximum date range is 375 days.
job_code_id		Returns timesheets with a matching job_code_id only.
users		Returns only timesheets for the specified user ID(s). Separate multiple IDs with a comma.

Output

• The output will include three top-level fields: status, message and data.
• status will either be 'ok' or 'fail'. On failure a last_error field will explain why, and the message and data fields won't be present.
• message will say something like 'Successfully retrieved timesheets' unless there is an error
• data will be an array of timesheets. Each record has the following fields:

Field	Description
ts_id	See Authentication section for details.
user_id	The ID of the user the timesheet is for.
username	The username of the user the timesheet is for.
clocked_in	Will always be 0 for now since this API call currently only retrieves "completed" timesheets.
start_time	The timesheet's start date adjusted for the user's timezone formatted as YYYY-MM-DD HH:MM:SS. This will be empty if the it's a "manual" timesheet.
end_time	The timesheet's end date adjusted for the user's timezone formatted as YYYY-MM-DD HH:MM:SS. This will be empty if the it's a "manual" timesheet.
start_time_gmt	The timesheet's start date formatted as YYYY-MM-DD HH:MM:SS. This will be empty if the it's a "manual" timesheet.
end_time_gmt	The timesheet's end date formatted as YYYY-MM-DD HH:MM:SS. This will be empty if the it's a "manual" timesheet.
tz	The user's numeric timezone when the timesheet was created. Example: -8.
total_seconds	Total number of seconds worked.
total_hours	Total number of hours worked, rounded to two decimal places. Example: 4.97
ip_in	The IP address of the user at clock-in. Example: 173.230.128.36
ip_out	The IP address of the user at clock-out. This will be 0.0.0.0 for manual timesheets. Example: 173.230.128.36
location	A textual name describing the user's location at clock-in and clock-out. Example: "Cell phone". If the location was a guess based on their IP address it will look something like "Los Angeles, CA?"
locked	Will be 1 if the timesheet is locked. Timesheets can be locked for various reasons, for example it has been exported for payroll. Note: Presently if the timesheet is locked because you have the Timesheet Approvals add-on installed and the timesheet is locked because it was approved by a manager this field will still show it as unlocked. This will be resolved at a later time.
exported	Will be 1 if the timesheet has been marked as exported for payroll. Otherwise will be marked as 0.
jobcode_id	The ID of the job-code, if any.
jobcode	The name of the job-code, if any.
custom_fields	Beta. Only for customers with custom fields. Contact us for details.
notes	The timesheet's notes.

Log a Failed Request

The "log_failed_request" API action is useful if you're trying to synch actions that were completed while offline, and you encounter conflicts or errors. If you cannot complete an action, you can at least log it so that it can be reviewed later by the TSheets team to determine the cause of the failure/conflict. The following parameters are available:

Action

• log_failed_request

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.
data	Yes	The API action (and accompanying parameters) that failed. This string must be url-encoded to ensure any special characters in the string are successfully passed to the API.

Examples

• If you receive an error when trying to pass 'action=clock_in&job_code_id=123', you could log the action before moving on, like so:

https://demo.tsheets.com/api.php?token=ff0c0144e68c1f29bb3795453862f78f&action=log_failed_request&data=action%3Dclock_in%26job_code_id%3D123

Output

• The output will be indication of whether or not the action was successful.

Logging Out

Calling this action will destroy the token associated with this user and all attributes associated with the user will be unavailable. A new token must be requested and the login action will need to be called again before doing anything else.

Action

• logout

Parameters

Parameter	Required	Description
token	Yes	See Authentication section for details.

Output

• The status will either be 'ok' if the user was logged out successfully, or fail. On failure a last_error field will explain why.