Request Formats

Last Updated: August 24, 2017

Retrieve resources with the HTTP GET Method

You can retrieve a representation of an object by sending an HTTP GET action to the resource's endpoint url. Filters can be specified for the request using a query string following the endpoint url. For example, you could GET a list of users, showing 5 per page and having the username 'frank' or 'fred' with the following:

curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/users?per_page=5&usernames=frank,fred"
    

Add/create new resources with the HTTP POST Method

You can add a new object by sending an HTTP POST action to the resource's endpoint url. You must include a JSON representation of the object in your POST body, and the "Content-Type: application/json" header must be set in your request. For example, you could POST a new user via the curl command-line utility like below. This assumes that you have a file, 'tsuser_create_json', that contains the JSON representation of your user:

curl -H "Authorization: Bearer <Access-Token>" -X POST -i -H "Content-Type: application/json" -d @tsuser_create_json "https://rest.tsheets.com/api/v1/users"
    

Edit existing resources with the HTTP PUT Method

You can edit an existing object by sending an HTTP PUT action to the resource's endpoint url. You must include a JSON representation of the object's modified properties in your POST body, and the "Content-Type: application/json" header must be set in your request. For example, you could PUT changes to an existing user via the curl command-line utility like below. This assumes that you have a file, 'tsuser_edit_json', that contains the JSON representation of your user, with a unique identifier for the user and the properties and their values that you would like changed for the user:

curl -H "Authorization: Bearer <Access-Token>" -X PUT -i -H "Content-Type: application/json" -d @tsuser_edit_json "https://rest.tsheets.com/api/v1/users"
    

Delete resources with the HTTP DELETE Method

You can delete an existing object by sending an HTTP DELETE action to the resource's endpoint url. An HTTP DELETE is similar to a GET, where all relevant parameters are passed as part of a query string. You must include an identifying id of some sort for the object you would like to delete as part of your parameters. For example, you could DELETE users 'joni' and 'frank' via the curl command-line utility like below.

curl -H "Authorization: Bearer <Access-Token>" -X DELETE -i "https://rest.tsheets.com/api/v1/users?usernames=joni,frank"
    

Possible Response Status Codes

  • 2xx response codes: All 2xx response codes indicate success for the action requested. Following are the most common 2xx response codes:
    • 200 OK: The request was successful and the response body contains the response for the action requested. Usually comes in response to a GET request.
    • 201 Created: The request was successful and the response body contains the response for the action requested. A 201 indicates that changes may have been made on the server side to the object when the request was handled (e.g. a timesheet was split due to break settings). The caller should check the supplemental_data of the response to process any related changes. Usually comes in response to a POST(create) or PUT (edit) request.
    • 202 Accepted: The request was successful and the response body contains the response for the action requested. A 202 indicates that the details of the create request match an already existing, active object. Rather than create a duplicate object, a 202 is returned along with the id of the original object. Usually comes in response to a POST(create) request.
  • 3xx response codes: All 3xx response codes indicate that you need to look elsewhere for your result. The response body will contain directions on where you should be redirected to.
  • 4xx response codes: All 4xx response codes indicate failure for the action requested. Following are the most common 4xx response codes:
    • 400 Bad Request: There was something wrong with your request.
    • 401 Unauthorized: You don't have sufficient permission to perform the action you requested.
    • 402 Billing not current: Your account billing is not current, so access was denied.
    • 405 Method Not Allowed: The action you are trying to perform is not allowed.
    • 406 Not Acceptable: The data you have tried to create conflicts with existing data.
    • 409 Conflict: The data you have tried to modify conflicts with existing data.
    • 413 Max items exceeded: The number of objects you are listing or editing or adding is too large.
    • 417 Expectation Failed: Your request was missing required parameters or your request was somehow otherwise malformed.
    • 429 Too many requests: You have sent too many requests to the API in too short a time. You'll have to try your requests again later.
  • 5xx response codes: All 5xx response codes indicate a server error or exceptional condition on the TSheets side. Following are the most common 5xx response codes:
    • 500 Internal Server Error: There was an unspecified error on the TSheets side. Try your request again in a moment; if you receive the same error then wait a few minutes before repeating it, as we are probably working to correct it. If you continue to receive the error after several hours, contact us to report a bug.
    • 501 Method not implemented: This method is not implemented for this object. It may be in the future.
    • 503 <Various messages>: A 503 response code indicates that the service is temporarily unavailable. Wait a few minutes for the condition to clear, and try again.

Response Formats

TSheets returns resource representations as JSON, unless an exception occurs. Each JSON response object will contain the response data underneath an object property labeled 'results'.

For GET requests, in the response body there will also be a boolean with the name, "more". If true, it means that there is another page of objects that can be retrieved. Otherwise false will be the value.

If the resource object references any other objects via an id (i.e. group_id), a corresponding JSON representation of that object will be contained in another top level property labeled 'supplemental_data'.

HTTP/1.1 200 OK
Date: Fri, 12 Jul 2013 18:25:58 GMT
Server: Apache
Expires: 0
Cache-Control: no-cache, must-revalidate
Pragma: no-cache
Content-Length: 7335
Content-Type: application/json

{
 "results": {
  "users": {
   "1283037": {
    "id": 1283037,
    "first_name": "Joni",
    "last_name": "Smith",
    "group_id": 0,
    "active": true,
    "employee_number": 0,
    "salaried": false,
    "exempt": false,
    "username": "joni",
    "email": "",
    "payroll_id": "",
    "hire_date": "0000-00-00",
    "term_date": "0000-00-00",
    "job_title": "",
    "gender": "",
    "last_modified": "2013-07-12T17:24:33+00:00",
    "last_active": "",
    "created": "2013-07-12T17:24:33+00:00",
    "mobile_number": "",
    "permissions": {
     "admin": false,
     "mobile": false,
     "status_box": false,
     "reports": false,
     "manage_timesheets": false,
     "manage_authorization": false,
     "manage_users": false,
     "manage_my_timesheets": false,
     "manage_jobcodes": false,
     "approve_timesheets": false,
     "manage_no_schedules": false,
     "manage_my_schedule": false,
     "manage_schedules": false,
     "manage_company_schedules": false,
     "view_my_schedules": false,
     "view_group_schedules": false,
     "view_company_schedules": false
    }
   }
  }
 },
 "more": false,
 "supplemental_data": {
  "groups": {
   "144959": {
    "id": 144959,
    "name": "test3",
    "last_modified": "2013-07-12T15:32:25+00:00",
    "created": "2013-07-12T15:32:25+00:00"
   },
  }
 }
}
    

Exceptions

TSheets returns exceptions in the HTTP response body when something goes wrong. An exception has the following properties:

Property Description
code The HTTP status code for the exception
message A descriptive message regarding the exception.