API

From WikiTSheets

This page is part of the TSheets User Guide

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

Contents 1 Overview 1.1 Getting Started 1.2 What You Should Know 2 Downloads 2.1 PHP API Toolkit 2.2 Perl API Toolkit 3 API Actions 3.1 Authentication 3.2 Tracking Time 3.2.1 Clocking In 3.2.2 Switching Job Codes 3.2.3 Timesheet Notes 3.2.4 Clocking Out 3.3 Location Information 3.3.1 Recording GPS Data 3.4 Read-Only Information 3.4.1 Retrieving Properties 3.4.2 Account related properties 3.4.3 Timesheets, Day and Week Totals 3.4.4 Other Properties 3.5 Job Codes 3.5.1 List Job Codes 3.5.2 Add a Job Code 3.5.3 Edit a Job Code 3.5.4 Delete a Job Code 3.5.5 Duplicate a Job Code 3.5.6 Assign a Job Code to Users 3.5.7 Unassign a Job Code from Users 3.6 User Management 3.6.1 Add a User 3.6.2 Edit a User 3.6.3 Delete a User 3.7 Reporting 3.7.1 Get Timesheets 3.8 Log a Failed Request 3.9 Logging Out

Overview

• 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.

• 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

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/

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

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, the following parameters are necessary:

• 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.

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

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.

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.

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.

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.

---

Location Information

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

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.

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)
• 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)

• 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)

Timesheets, Day and Week Totals

• logged_in (whether or not the user is logged in)
• clocked_in (whether or not the user is clocked in)
• 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)

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

The "jobcode_list" API action will retrieve a list of all job codes the currently authenticated user has access to. If the currently authenticated user is an admin or has sufficient permissions, then all jobcodes 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

• jobcode_list

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.
parent_id		Will only return jobcodes with this parent_id. Parent_id of zero returns all jobcodes

Output

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

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.
sms_code		The SMS alias to be used for this jobcode 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 jobcode that was just added.

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.
sms_code		The SMS alias to be used for this jobcode 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 jobcode that was just edited.

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.

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.
sms_code		The SMS alias to be used for this jobcode 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 jobcode that was just duplicated.

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.

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

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)
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.

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.

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 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.
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.
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.

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.

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.