Introduction

TSheets is now QuickBooks Time

The TSheets API provides access to the same rich features as our top-rated web-based and mobile apps. With it you can quickly build time-tracking solutions that simplify workflows and save customers time and money. For inspiration, have a look at the amazing integrations our partners have built on our App Marketplace.

Based on REST principles, it's very easy to write and test applications. You can use your browser to access URLs, and practically any TLS-capable HTTP client in any programming language to interact with the API. The API allows you to query metadata about your account, users, jobcodes, timesheets, GPS points, and custom fields. You can also create timesheets, users, jobcodes, etc. All access to the API occurs over a TLS-encrypted secure channel, so your API client must support TLS. To ensure data privacy, unencrypted HTTP is not supported.

Getting Started

1) Signup for a Free Trial
Visit our site today and get started within minutes

2) Obtain an Access Token
See the guided walkthrough to complete the simple steps. (See also Authentication)

3) Build your Integration
For the quickest start, try our Postman Collection along with the API Reference documentation.

Postman Collection

The quickest way to get started is to use our Postman request collection. The following steps will help you get up and running. If you prefer, our API can also easily be explored with other tools, like cURL.

1) Open the TSheets Postman Collection

2) Configure the Postman Environment

Setup a new environment by clicking the Gear icon at top right
Name the new environment TSheets and click Add to create
Expand the GET STARTED folder and select the Environment Setup method
Select the Pre-req. tab and set tsheets-bearer-token to the Access Token Value previously obtained
Click the Send button

3) Explore the API

Execute any of the requests within the collection
Refer to this documentation for the requirements of each method

Base URL

All URLs referenced in the documentation have the following base:

https://rest.tsheets.com/api/v1

Contribute

Found an error, or would otherwise like to contribute to our API documentation? Submit a pull request to our public GitHub repository.

Request Throttling

To prevent abuse of the TSheets API, we limit requests to a maximum of 300 calls within any 5 minute time window (subject to change). Rate limiting is primarily considered on a per-connection basis (per access token). If you exceed the current rate limit, you will receive a 429 'Too many requests' response from our API. You will continue to receive a 429 response until you're out of the current time window. The threshold and time window may adjust dynamically downward if you are found to be abusing the system.

Response Size Limit

Each request response will return a maximum of 200 results per page (regardless of whether the limit parameter is sent with your request). To receive the full response, look for the "more": true attribute and iterate sending a new request with the page parameter incremented until you receive "more": false in the response payload.

SDK's & Helper Libraries

This documentation explains the format for calls to the TSheets API with code snippets in cURL and several other languages. Full SDK's and helper libraries are also available upon request to make it even easier for you to get started with TSheets.

Full SDK's

C#.NET Standard (hosted on GitHub)

Helper Libraries

PHP Library (hosted on GitHub)
C#/.NET Framework Library (hosted on GitHub)
Request a library for your favorite language

While a helper library can make it easier to consume the API, it is certainly not necessary and the API is still very straight-forward to use even without one. Simply use a built-in http class or library for your language of choice.

Java, use URLConnection or the Apache HttpComponents
Ruby, use Net::HTTP
Perl, use HTTP::Client

Connection Count Information

By default we allow you to connect to 3 additional client accounts (besides your own) via your API application keys. If you are building an integration and are interested in enabling your application for use by any TSheets customer, please contact us.

Here are a few of the things we'll be looking for before allowing your application access to our other TSheets customers:

Are you obtaining tokens by directing the user through our OAuth flow?
Are you storing the API App client_id and client_secret encrypted?
Are you storing OAuth tokens encrypted?
Do you have a mechanism in place for refreshing OAuth tokens before they expire - to prevent people from needing to log in again?
If you are unable to refresh the token, what is the user experience for logging in and renewing it?
What permissions are required for your app to do its work? Are you checking those permissions for the user tied to the OAuth token - and not just assuming you'll have it?
When checking for changes to data, are you using the last_modified_timestamps endpoint?
How are changes to data being checked from your app? Polling? Manually? Both? If you're polling, how often?
If client doesn't have a TSheets account, are you utilizing the account creation mechanism available via the OAuth flow?
On initial sync, are you getting all data? On subsequent syncs, are you utilizing last_modified times to pull data?
When editing or creating multiple objects, are you doing so via batch operations (i.e. up to 200 with one request vs. a separate request for each)?

Getting Help

If you have any questions using our API, please visit Intuit Developer Site or QuickBooks Community Page.

Authentication

OAuth2.0

TSheets uses OAuth2 for authentication and authorization of our API. OAuth2 is a protocol designed to let third-party applications authenticate to perform actions as a user, without getting the user's password. There are several libraries available that implement the protocol, and a good list can be found at the OAuth2 home page. Through the use of OAuth2, you'll go through the process of obtaining a token and then you'll use that token in every request made to the API to verify your identity.

Obtaining a Token

Before you can make any request of the API, you must first authenticate. Once you've authenticated, you will be given an access token that may be used for all subsequent requests.

If you need a small number of access tokens, implementing the full OAuth2 flow can be cumbersome. Sometimes you just want a token for development purposes. As a convenience to you we allow access tokens to be created through the web UI via the API Add-on preferences page: Feature Add-ons -> API -> click 'Add a new application' (See also guided walkthrough). You can also extend the expiration date on these tokens via the web UI, so that you don't have to deal with refreshing tokens. Remember to keep your access tokens secret; treat them just like passwords!

Performing the OAuth2 token request flow requires an OAuth client ID and an OAuth client secret. To obtain these application credentials, you will need to install the API Add-On in your TSheets account and follow the instructions found there. The OAuth client secret should never be shared.

There are 2 steps required in order to obtain an access token, as follows:

Step 1. Authorization Request

This first step consists of a user authorizing your application to access their information on TSheets. To do this, you'll create a link somewhere on your site that they can use to initiate the process. The link will contain several parameters that are necessary for TSheets to consider it valid. The user should use a web browser to follow the link and perform the authorization request.

Once the user is directed to access the authorization endpoint at TSheets ('authorization server' in OAuth2-speak), two things will happen:

The user ('resource owner' in OAuth2-speak) will need to log in using their TSheets credentials.
Once they've successfully logged in, they're given a choice of whether or not to grant your application access to their data within TSheets. If they do, TSheets will generate an authorization code and redirect the user back to your redirect_uri with the authorization code as one of the parameters in the request.

The link that a user will follow to perform an authorization request is made to the /authorize end-point:

Example: Authorization Request.

Request

curl "https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE" \

var client = new RestClient("https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE");
var request = new RestRequest(Method.GET);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE")
Dim request = New RestRequest(Method.[GET])
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE")
  .get()
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE",
  "method": "GET",
  "headers": {
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/authorize',
  qs: {
    response_type: 'code',
    client_id: 'MYAPPCLIENTID',
    redirect_uri: 'https://somedomain.com/callback',
    state: 'MYSTATE',
  },
  headers: 
   {
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/authorize');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'response_type' => 'code',
  'client_id' => 'MYAPPCLIENTID',
  'redirect_uri' => 'https://somedomain.com/callback',
  'state' => 'MYSTATE',
));

$request->setHeaders(array(
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/authorize"

querystring = {
  "response_type":"code",
  "client_id":"MYAPPCLIENTID",
  "redirect_uri":"https://somedomain.com/callback",
  "state":"MYSTATE",
}

payload = ""
headers = {
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE"

  req, _ := http.NewRequest("GET", url, nil)


  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();


$url="https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

HTTP Request

get https://rest.tsheets.com/api/v1/authorize

Parameters


response_type required	String	This parameter MUST always be set to the string 'code'.
client_id required	String	This parameter MUST always be set to the value of the OAuth client ID that you obtained when you registered your app in the TSheets API Add-On in your TSheets account.
redirect_uri required	String	The HTTPS url that you submitted as the 'OAuth Redirect URI' when you set up your app in the TSheets API Add-On. If the user grants access to your application, we'll redirect them back to this url with a temporary code in a `code` parameter. They'll use this code to obtain an access token.
state required	String	A random value used by the client to maintain state between the request and callback. The authorization server includes this value when redirecting the user-agent back to the client. It is used to protect against cross-site request forgery attacks. If the states don't match, the request has been created by a third party and the process should be aborted.
display_mode optional	String	Optional. Can be 'create' or 'login'. Default is 'login'. If 'login', the form for logging into an existing TSheets account is displayed first. If 'create', the form for creating a new TSheets account is shown first.

Upon successful authorization and if the user grants access for their data to the app, TSheets will redirect the connected user to the redirect_uri (https://somedomain.com/callback in this example) found in the original request, and two parameters will be appended to it:

1) code - the unique code generated for this request - to be used in the token call later in the flow.
2) state - the value passed in 'state' in the original authorization request.

For example:

https://somedomain.com/callback?code=bbcaef03191517dfb60d0305bfea38ea995af1az&state=MYSTATE

The server that handles the request to https://somedomain.com/callback should extract and save the code parameter value, as it is required as part of the next step in the flow. The state value should be compared to what was originally sent and verified to be the same.

If the call to the /authorize end-point is malformed, or if the user denies access to the requesting app, then TSheets will still redirect the user back to the redirect_uri, but instead it will append error and error_description parameters. For example:

https://somedomain.com/callback?error=SOME_ERROR&error_description=SOME_DESCRIPTION

We do not currently support scope for our clients, so the scope parameter mentioned in the OAuth 2.0 specification is not required.

Step 2. Access Token Request

At this point you have an authorization 'code' for the user of your app. To exchange the code for an access token, your application needs to do a POST to our /grant API end-point. In this step, TSheets will check that the authorization code was issued to the same application that is making the token request.

The access_token should be included with every call to the API. Failure to include the access token or using an expired token will result in a 401 response. Note that when you receive your access token, you also receive the user_id and client_id properties that are associated with the user that the access token is for. These properties are provided for convenience, to potentially save you the need for making a request to the current user endpoint.

If the client has IP Authorization security enabled with the block all access option turned on, the request could fail with a 499 status code if it comes from an unauthorized IP address. All subsequent requests will also fail until the device switches to an authorized IP address.

Example: Access Token Request.

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/grant \
  -d 'grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback'

var client = new RestClient("https://rest.tsheets.com/api/v1/grant");
var request = new RestRequest(Method.POST);
request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/grant")
Dim request = New RestRequest(Method.POST)
request.AddParameter("application/x-www-form-urlencoded", "grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/grant")
  .post(body)
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/authorize?response_type=code&client_id=MYAPPCLIENTID&redirect_uri=https://somedomain.com/callback&state=MYSTATE",
  "method": "POST",
  "headers": {
  },
  "processData": false,
  "data": {
    "grant_type": "authorization_code",
    "client_id": "MYAPPCLIENTID",
    "client_secret": "MYAPPSECRET",
    "code": "bbcaef03191517dfb60d0305bfea38ea995af1az",
    "redirect_uri": "https%3A%2F%2Fsomedomain.com%2Fcallback"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/grant',
  headers: 
  { 
  },
  form:
   {
      grant_type: 'authorization_code',
      client_id: 'MYAPPCLIENTID',
      client_secret: 'MYAPPSECRET',
      code: 'bbcaef03191517dfb60d0305bfea38ea995af1az',
      redirect_uri: 'https%3A%2F%2Fsomedomain.com%2Fcallback' }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/grant');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
));

$request->setContentType('application/x-www-form-urlencoded');
$request->setPostFields(array(
  'grant_type' => 'authorization_code',
  'client_id' => 'MYAPPCLIENTID',
  'client_secret' => 'MYAPPSECRET',
  'code' => 'bbcaef03191517dfb60d0305bfea38ea995af1az',
  'redirect_uri' => 'https%3A%2F%2Fsomedomain.com%2Fcallback'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/grant")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request.body = "grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/grant"

payload = "grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback"
headers = {
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/grant"

  payload := strings.NewReader("grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback")

  req, _ := http.NewRequest("POST", url, payload)


  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
]

let postData = NSMutableData(data: "grant_type=authorization_code".data(using: STring.Encoding.utf8)!)
postData.append("&client_id=MYAPPCLIENTID".data(using: String.Encoding.utf8)!)  
postData.append("&client_secret=MYAPPSECRET".data(using: String.Encoding.utf8)!)  
postData.append("&code=bbcaef03191517dfb60d0305bfea38ea995af1az".data(using: String.Encoding.utf8)!)  
postData.append("&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback".data(using: String.Encoding.utf8)!)  

let request = NSMutableURLRequest(
  url: NSURL(string: "http://rest.tsheets.com/api/v1/grant")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();


$req = 'grant_type=authorization_code&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&code=bbcaef03191517dfb60d0305bfea38ea995af1az&redirect_uri=https%3A%2F%2Fsomedomain.com%2Fcallback';

$url="http://rest.tsheets.com/api/v1/grant"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "access_token":"84ec7a2f2b1379990caea347d67e713f34f2d5dz",
  "expires_in":864000,
  "token_type":"bearer",
  "scope":"",
  "refresh_token":"0ed645dbcfaca681e37df26df6f39d273330e7a0",
  "user_id":"12345",
  "company_id":"12345",
  "client_url":"blakemoving"
}

HTTP Request

post https://rest.tsheets.com/api/v1/grant

Parameters


grant_type required	String	This parameter MUST always be set to the string 'authorization_code'. This tells us what type of code is included.
client_id required	String	This parameter MUST always be set to the value of the OAuth client ID that you obtained when you set up your app in the API Add-On in your TSheets account.
client_secret required	String	This parameter MUST always be set to the value of the OAuth client secret that you obtained when you set up your app in the API Add-On in your TSheets account.
code required	String	The 'code' being exchanged for an access token. This should be the authorization code received above.
redirect_uri required	String	The HTTPS url that was included in Step 1 of the authorization request. The value must be identical.

Make Requests With the Access Token

Example: Making a request with an access token.

Request

curl "https://rest.tsheets.com/api/v1/users?limit=1" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/users?limit=1");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/users?limit=1")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/users?limit=1")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/users?limit=1",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/users',
  qs: {
    limit: '1',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/users');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'limit' => '1',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/users?limit=1")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/users"

querystring = {
  "limit":"1",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/users?limit=1"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/users?limit=1")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/users?limit=1"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Once you have an OAuth access token, you can use it to make API requests. Use the HTTP Authorization header when making a request.

Storing a Token

When appropriate, applications should store the token locally, rather than requesting a new token for the same user each time the user uses the application. If the token is deleted or expires, the application will get a 401 Unauthorized error from the API, in which case the application should perform the OAuth flow again to receive a new token. Storing a token is in many ways equivalent to storing the user's password, so tokens should be stored and used in a secure manner.

Refreshing an Access Token

Access tokens expire after expires_in seconds (see example response). In order to avoid sending the user through the OAuth2 process described above every time they want to access resources, API consumers can exchange a refresh_token for a new access_token before the current one expires. To do so, you make a request similar to the original request described above.

Example: Refresh Token Request.

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/grant \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/x-www-form-urlencoded' \
  -d 'grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0'

var client = new RestClient("https://rest.tsheets.com/api/v1/grant");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/x-www-form-urlencoded");
request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/grant")
Dim request = New RestRequest(Method.POST)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/x-www-form-urlencoded")
request.AddParameter("application/x-www-form-urlencoded", "grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/x-www-form-urlencoded");
RequestBody body = RequestBody.create(mediaType, "grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/grant")
  .post(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/x-www-form-urlencoded")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/users?limit=1",
  "method": "POST",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/x-www-form-urlencoded",
  },
  "processData": false,
  "data": {
    "grant_type": "refresh_token",
    "client_id": "MYAPPCLIENTID",
    "client_secret": "MYAPPSECRET",
    "refresh_token": "0ed645dbcfaca681e37df26df6f39d273330e7a0"
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/grant',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/x-www-form-urlencoded',
  },
  form:
   {
      grant_type: 'refresh_token',
      client_id: 'MYAPPCLIENTID',
      client_secret: 'MYAPPSECRET',
      refresh_token: '0ed645dbcfaca681e37df26df6f39d273330e7a0' }
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/grant');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/x-www-form-urlencoded',
));

$request->setContentType('application/x-www-form-urlencoded');
$request->setPostFields(array(
  'grant_type' => 'refresh_token',
  'client_id' => 'MYAPPCLIENTID',
  'client_secret' => 'MYAPPSECRET',
  'refresh_token' => '0ed645dbcfaca681e37df26df6f39d273330e7a0'
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/grant")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/x-www-form-urlencoded',
request.body = "grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/grant"

payload = "grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/x-www-form-urlencoded',
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/grant"

  payload := strings.NewReader("grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/x-www-form-urlencoded")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/x-www-form-urlencoded",
]

let postData = NSMutableData(data: "grant_type=refresh_token".data(using: STring.Encoding.utf8)!)
postData.append("&client_id=MYAPPCLIENTID".data(using: String.Encoding.utf8)!)  
postData.append("&client_secret=MYAPPSECRET".data(using: String.Encoding.utf8)!)  
postData.append("&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0".data(using: String.Encoding.utf8)!)  

let request = NSMutableURLRequest(
  url: NSURL(string: "http://rest.tsheets.com/api/v1/grant")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/x-www-form-urlencoded');

$req = 'grant_type=refresh_token&client_id=MYAPPCLIENTID&client_secret=MYAPPSECRET&refresh_token=0ed645dbcfaca681e37df26df6f39d273330e7a0';

$url="http://rest.tsheets.com/api/v1/grant"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "access_token":"c65931f72f0a905bea92fb2dce8e4c25151c02e9",
  "expires_in":864000,
  "token_type":"bearer",
  "scope":"",
  "refresh_token":"9eaec192df27b22e6575e438a4159639937605c7",
  "user_id":"12345",
  "company_id":"12345",
  "client_url":"blakemoving"
}

HTTP Request

post https://rest.tsheets.com/api/v1/grant

Parameters


grant_type required	String	This parameter MUST be set to the string 'refresh_token'.
client_id required	String	This parameter MUST always be set to the value of the OAuth client ID that you obtained when you set up your app in the API Add-On in your TSheets account.
client_secret required	String	This parameter MUST always be set to the value of the OAuth client secret that you obtained when you set up your app in the API Add-On in your TSheets account.
refresh_token required	String	This parameter is the `refresh_token` that you're exchanging for a `new access_token`.

Request Formats

Retrieve resources with the HTTP GET Method

Example: Retrieving a resource.

Request

curl "https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/users',
  qs: {
    limit: '5',
    usernames: 'frank,fred',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/users');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'limit' => '5',
  'usernames' => 'frank,fred',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/users"

querystring = {
  "limit":"5",
  "usernames":"frank,fred",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

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

Create new resources with the HTTP POST Method

Example: Creating a new resource.

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/users \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/users");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/users")
Dim request = New RestRequest(Method.POST)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/users")
  .post(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred",
  "method": "POST",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/users',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/users');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/users")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/users"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/users"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/users")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="https://rest.tsheets.com/api/v1/users"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

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.

Update existing resources with the HTTP PUT Method

Example: Updating a resource.

Request

curl -X PUT \
  https://rest.tsheets.com/api/v1/users \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/users");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/users")
Dim request = New RestRequest(Method.PUT)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/users")
  .put(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/users?limit=5&usernames=frank,fred",
  "method": "PUT",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'PUT',
  url: 'https://rest.tsheets.com/api/v1/users',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/users');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/users")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/users"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("PUT", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/users"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("PUT", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "http://rest.tsheets.com/api/v1/users")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="http://rest.tsheets.com/api/v1/users"; 

$client->PUT($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

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 PUT body, and the Content-Type: application/json header must be set in your request. For example, you could PUT changes using the user's unique id and the properties and values that you would like changed:

Delete resources with the HTTP DELETE Method

Example: Deleting resources.

Request

curl -X DELETE "https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078"
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078");
var request = new RestRequest(Method.DELETE);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078")
Dim request = New RestRequest(Method.[DELETE])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078")
  .delete()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078",
  "method": "DELETE",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'DELETE',
  url: 'https://rest.tsheets.com/api/v1/jobcode_assignments',
  qs: {
    ids: '56788,58078',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/jobcode_assignments');
$request->setMethod(HTTP_METH_DELETE);

$request->setQueryData(array(
  'ids' => '56788,58078',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Delete.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/jobcode_assignments"

querystring = {
  "ids":"56788,58078",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078"

  req, _ := http.NewRequest("DELETE", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "DELETE"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/jobcode_assignments?ids=56788,58078"; 

$client->DELETE($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

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.

Note: Some endpoints which do not support DELETE instead allow items to be "archived" (aka soft deleted). For example, you can make a PUT call with active=false to the Users endpoint to remove a user.

Possible HTTP Response Status Codes

2xx response codes

All 2xx response codes indicate that the request was successful. The response body contains any details for the action requested.

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.
`409 Conflict`	There is a conflict with the operation you're trying to perform (details in the response body).
`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.

`_status_code`'s in the Response Body

Please note that the API will include a _status_code in the response body associated with each element that was passed in a POST or PUT request. These _status_code's will have similar values to the HTTP Response codes listed above, but they don't necessarily have the same meaning. You can find documentation on each _status_code that may be returned as part of each API endpoint's documentation.

Response Formats

Example

{
  "results": {
    "users": {
      "933849": {
        "id": 933849,
        "first_name": "Mary",
        "last_name": "Samsonite",
        "group_id": 0,
        "active": true,
        "employee_number": 0,
        "salaried": false,
        "exempt": false,
        "username": "admin",
        "email": "admin@example.com",
        "email_verified": false,
        "payroll_id": "",
        "mobile_number": "2087231456",
        "hire_date": "0000-00-00",
        "term_date": "0000-00-00",
        "last_modified": "2018-03-28T17:24:20+00:00",
        "last_active": "",
        "created": "2018-03-27T16:13:34+00:00",
        "client_url": "api_sample_output",
        "company_name": "API Sample Output Company",
        "profile_image_url": "https:\/\/www.gravatar.com\/avatar\/e64c7d89f26bd1972efa854d13d7dd61",
        "display_name": null,
        "pto_balances": {
          "2624351": 0,
          "2624353": 0,
          "2624355": 0
        },
        "submitted_to": "2000-01-01",
        "approved_to": "2000-01-01",
        "manager_of_group_ids": [ ],
        "require_password_change": false,
        "pay_rate": 0,
        "pay_interval": "hour",
        "permissions": {
          "admin": true,
          "mobile": true,
          "status_box": false,
          "reports": false,
          "manage_timesheets": false,
          "manage_authorization": false,
          "manage_users": false,
          "manage_my_timesheets": false,
          "manage_jobcodes": false,
          "pin_login": false,
          "approve_timesheets": false,
          "manage_schedules": false,
          "external_access": false,
          "manage_my_schedule": false,
          "manage_company_schedules": false,
          "view_company_schedules": false,
          "view_group_schedules": false,
          "manage_no_schedules": false,
          "view_my_schedules": false
        },
        "customfields": ""
      }
    }
  },
  "more": false,
  "supplemental_data": {
    "jobcodes": {
      "2624351": {
        "id": 2624351,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "pto",
        ...
      },
      "2624353": {
        "id": 2624353,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "pto",
        ...
      },
      "2624355": {
        "id": 2624355,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "pto",
        ...
      }
    }
  }
}

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.

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.

Tips & Suggestions

Requesting items that have changed since you last made a request to the API

When you are looking to see whether any items have changed since your last request, it is best to query the last_modified_timestamps API endpoint. This will allow you to easily make a single API query and see the most recent time any object from an endpoint was modified.

When you determine that you need to query an endpoint, use the modified_since parameter to get only those items that have been modified since the last time you made a request.

Working with Jobcodes & Jobcode Assignments

When working with Jobcodes it is highly recommended to use the Jobcode Assignments endpoint whenever possible in order to limit the number of jobcodes returned from a request. This becomes very important when dealing with TSheets accounts connected with external services such as Quickbooks since it is likely that the account will have a large number of Jobcodes.

Archiving objects no longer in use

To keep your account running as efficiently as possible, it is a good idea to archive certain objects once you are done with them. You can archive Users, Jobcodes, and Customfielditems when they're no longer actively being used. You do this by setting their active field to false. All of these items are still represented in reports, even though they're archived.

You cannot archive timesheets. If you delete a timesheet, it is permanently removed. To retain the ability to perform historical reporting on time, we recommend that you do not delete timesheets, unless it's for the purpose of correcting an inaccuracy.

Handling Supplemental Timesheet Data

Example: Suppemental Data.

Request

curl "https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/timesheets',
  qs: {
    start_date: '12-05-2017',
    modified_since: '12-05-2018',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/timesheets');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'start_date' => '12-05-2017',
  'modified_since' => '12-05-2018',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/timesheets"

querystring = {
  "start_date":"12-05-2017",
  "modified_since":"12-05-2018",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/timesheets?start_date=12-05-2017&modified_since=12-05-2018"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "timesheets": {
      "142835829": {
        "id": 142835829,
        "user_id": 1396641,
        "jobcode_id": 20355120,
        "start": "2018-07-23T10:00:00-07:00",
        "end": "2018-07-23T13:10:23-07:00",
        "duration": 11423,
        "date": "2018-07-23",
        "tz": -7,
        "tz_str": "",
        "type": "regular",
        "location": "TSheets API Tester",
        "active": "0",
        "locked": 0,
        "notes": "This is a test of the emergency broadcast system",
        "customfields": {
          "24068": "",
          "24066": ""
        },
        "last_modified": "2018-12-13T22:52:08+00:00"
      },
      "142835831": {
        "id": 142835831,
        "user_id": 1396641,
        "jobcode_id": 20347779,
        "start": "2018-07-25T09:30:00-07:00",
        "end": "2018-07-25T13:10:23-07:00",
        "duration": 13223,
        "date": "2018-07-25",
        "tz": -7,
        "tz_str": "",
        "type": "regular",
        "location": "TSheets API Tester",
        "active": "0",
        "locked": 0,
        "notes": "This is a test",
        "customfields": {
          "24068": "",
          "24066": ""
        },
        "last_modified": "2018-12-13T20:30:42+00:00"
      }
    }
  },
  "more": false,
  "supplemental_data": {
    "jobcodes": {
      "20355120": {
        "id": 20355120,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "regular",
        ...
      },
      "20347779": {
        "id": 20347779,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "regular",
        ...
      }
    },
    "users": {
      "1396641": {
        "id": 1396641,
        "first_name": "API",
        "last_name": "Employee",
        "group_id": 0,
        "active": true,
        ...
      }
    },
    "customfields": {
      "24068": {
        "id": 24068,
        "required": false,
        "applies_to": "timesheet",
        "type": "free-form",
        ...
      },
      "24066": {
        "id": 24066,
        "required": false,
        "applies_to": "timesheet",
        "type": "managed-list",
        ...
      }
    }
  }
}

When fetching timesheets via TSheets, supplemental data that is pertinent to the timesheets returned will be sent back in a supplemental_data JSON object unless you exclude it with an API filter. Within this object you will find additional objects related to the timesheets that were returned in the result set. In the example, Jobcode, User, and Custom Field objects are returned if they are referenced in the timesheet results. This is done specifically to ensure that API consumers have all the necessary data to display any timesheets that are returned. Knowing this, it is a best practice for API consumers to always parse and store any supplemental data should they wish to persist and display these timesheets later (for offline viewing, etc).

You can exclude supplemental data from GET requests for the timesheets and other endpoints by including the parameter supplemental_data with a value of "no". If your application will not be using the supplemental data from a given request, you can include this parameter to reduce payload size and improve the response time.

Recipes for Some Common Workflows

Getting current status of a single user (whether on or off the clock)

Query the timesheets endpoint for the given user with active status = true over the last 7 days.

/timesheets?user_ids=[USER_ID]&on_the_clock=yes&start_date=[7_DAYS_AGO]

This works because:

We auto-clock-out any user after 7 days on the clock.
If you get a result back, they're currently on the clock and you'll have all the detail you need.
If they're off the clock, you'll get no result back.

Getting current status and totals of all users (or one) in compact format

Query the /reports endpoint for the 'current_totals' report (this is what fuels our "who's working" window in the web dashboard). This will get you a tally of time for the day and the current task and whether or not each user is on the clock at the moment.

Approving time

A user may submit their time (if configured to allow it), while managers and admins may approve time. PUT to the Users endpoint, modifying the submitted_to and/or approved_to properties.

Running Payroll

If you have the Approvals Add-On installed, then each user will have a submitted_to and approved_to property. When you query the /reports endpoint for a payroll report - entries will reference a user_id which will correspond to an entry in the supplemental_data portion of the response. You can check the approved_to property of each user via the supplemental_data in the response.

We recommend that you do one of two things:

1) Only use payroll entries where the user's time has been approved.

2) Use all payroll entries, but somehow distinguish (in the UI) between those who are approved versus those who are not.

Walkthroughs

Obtaining an API Access Token

This walkthrough will guide you through the process of creating an API App in TSheets and obtaining an API Access Token for use as the OAuth2 Bearer Token value in the Authentication header that is required when making a call to any of the API methods.

1) Install the API App Feature Add-On

Log into your TSheets Account and select the Feature Add-ons...Manage Add-ons... menu from the left navigation pane (actual menu layout may differ.)

2) Select the API Add-On and click Install

Afterwards, the API Add-On will be available from the Feature Add-ons section of the left navigation pane.

3) Add a New Application

Select Add a new application at bottom left. If the following window is not displayed, you can select API from Feature Add-ons on the left navigation pane.

4) Enter API Application Details

Add a short name and a meaningful description. For now, just use a dummy value for the Redirect URI. It can be edited later.

5) Create a New Token

Almost there! Click Add Token at bottom left. This step will generate a token for immediate use.

6) Capture the New Token Value for Use with the API

Copy the token value for use with API method calls, and be sure to Save before exiting. Congratulations! You may now explore the API with ease, fully authenticated.

End of Walkthrough.

Current User

The Current User Object

An instance of the User Object, but for the user associated with the current access token.

Retrieve the Current User

Example: Retrieve current user.

Request

curl "https://rest.tsheets.com/api/v1/current_user" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/current_user");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/current_user")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/current_user")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/current_user",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/current_user',
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/current_user');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/current_user")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/current_user"

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/current_user"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/current_user")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/current_user"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "users": {
      "933849": {
        "id": 933849,
        "first_name": "Mary",
        "last_name": "Samsonite",
        "group_id": 0,
        "active": true,
        "employee_number": 0,
        "salaried": false,
        "exempt": false,
        "username": "admin",
        "email": "admin@example.com",
        "email_verified": false,
        "payroll_id": "",
        "mobile_number": "2087231456",
        "hire_date": "0000-00-00",
        "term_date": "0000-00-00",
        "last_modified": "2018-03-28T17:24:20+00:00",
        "last_active": "",
        "created": "2018-03-27T16:13:34+00:00",
        "client_url": "api_sample_output",
        "company_name": "API Sample Output Company",
        "profile_image_url": "https:\/\/www.gravatar.com\/avatar\/e64c7d89f26bd1972efa854d13d7dd61",
        "display_name": null,
        "pto_balances": {
          "2624351": 0,
          "2624353": 0,
          "2624355": 0
        },
        "submitted_to": "2000-01-01",
        "approved_to": "2000-01-01",
        "manager_of_group_ids": [ ],
        "require_password_change": false,
        "pay_rate": 0,
        "pay_interval": "hour",
        "permissions": {
          "admin": true,
          "mobile": true,
          "status_box": false,
          "reports": false,
          "manage_timesheets": false,
          "manage_authorization": false,
          "manage_users": false,
          "manage_my_timesheets": false,
          "manage_jobcodes": false,
          "pin_login": false,
          "approve_timesheets": false,
          "manage_schedules": false,
          "external_access": false,
          "manage_my_schedule": false,
          "manage_company_schedules": false,
          "view_company_schedules": false,
          "view_group_schedules": false,
          "manage_no_schedules": false,
          "view_my_schedules": false
        },
        "customfields": ""
      }
    }
  },
  "more": false,
  "supplemental_data": {
    "jobcodes": {
      "2624351": {
        "id": 2624351,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "pto",
        ...
      },
      "2624353": {
        "id": 2624353,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "pto",
        ...
      },
      "2624355": {
        "id": 2624355,
        "parent_id": 0,
        "assigned_to_all": true,
        "billable": false,
        "active": true,
        "type": "pto",
        ...
      }
    }
  }
}

Retrieves the user object for the currently authenticated user. This is the user that authenticated to TSheets during the OAuth2 authentication process.

HTTP Request

get https://rest.tsheets.com/api/v1/current_user

Parameters

None

Custom Fields

Custom Fields (aka "Advanced Tracking") provide a means to extend the data that is tracked on employee time cards to capture custom activities beyond time tracking, e.g. mileage, equipment, expenses, etc. A maximum of 6 Custom Fields can be 'active' on an account at any given time.

The Custom Field Object

Example

{
  "id": 134913,
  "active": true,
  "required": true,
  "applies_to": "timesheet",
  "type": "managed-list",
  "short_code": "Exp",
  "regex_filter": "",
  "name": "Experience",
  "last_modified": "2019-02-10T20:40:41+00:00",
  "created": "2019-02-03T18:36:16+00:00",
  "ui_preference": "drop_down",
  "required_customfields": [],
  "show_to_all": false
}

Following is a list of the properties that belong to a customfield object, and a description of each.


id read-only	Int	Id of customfield.
active read-write	Boolean	true or false. If true, this custom field is active. If false, this custom field is archived.
name read-write	String	Name of the customfield.
short_code read-write	String	This is a shortened code or alias that is associated with the customfield. It may only consist of letters and numbers.
show_to_all read-write	Boolean	Declares whether this customfield should be shown on timesheets regardless of the jobcode chosen. If false, it will only appear when the chosen jobcode for a timesheet has been associated with this field. This field can only be set to false if the custom field is of type 'timesheet'.
required read-write	Boolean	true or false. Indicates whether a value for this customfield is required on a timesheet
applies_to read-write	String	'timesheet' or 'user' or 'jobcode'. Indicates what type of object this customfield applies to.
type read-only	String	'managed-list' or 'free-form'. If 'free-form', then it should be displayed in a UI as a text box, where users can enter values for this customfield and they'll get added automatically to the customfield if they don't already exist. If 'managed-list', then it should be displayed as a select-box and users can only choose an existing value.
ui_preference read-only	String	'drop_down' or 'text_box_with_suggest'. Indicates the suggested user interface depending on the specified type.
regex_filter read-only	String	Regular expression that will be applied to any new items as they're added to the customfield. If they do not match the regex_filter, they may not be added.
last_modified read-only	String	Date/time when this customfield was last modified, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
created read-only	String	Date/time when this customfield was created, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
required_customfields read-only	Array	Ids of customfields that should be displayed when this customfield is visible on a timecard

Retrieve Custom Fields

Example: Retrieve a list of all customfields.

Request

curl "https://rest.tsheets.com/api/v1/customfields" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfields");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfields")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfields")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfields",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfields',
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfields');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfields")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfields"

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfields"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfields")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfields"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Example: Retrieve a list of customfields with a given id.

Request

curl "https://rest.tsheets.com/api/v1/customfields?ids=195923" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfields?ids=195923");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfields?ids=195923")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfields?ids=195923")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfields?ids=195923",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfields',
  qs: {
    ids: '195923',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfields');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'ids' => '195923',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfields?ids=195923")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfields"

querystring = {
  "ids":"195923",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfields?ids=195923"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfields?ids=195923")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfields?ids=195923"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Example: Retrieve a list of customfields that have been modified since a given date.

Request

curl "https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfields',
  qs: {
    modified_since: '2018-01-01T00:00:00%2B00:00',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfields');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'modified_since' => '2018-01-01T00:00:00%2B00:00',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfields"

querystring = {
  "modified_since":"2018-01-01T00:00:00%2B00:00",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfields": {
      "195923": {
        "id": 195923,
        "active": true,
        "required": true,
        "applies_to": "timesheet",
        "type": "managed-list",
        "short_code": "e",
        "regex_filter": "",
        "name": "Equipment",
        "last_modified": "2018-04-04T15:37:30+00:00",
        "created": "2018-03-27T16:13:35+00:00",
        "ui_preference": "drop_down",
        "required_customfields": [ ],
        "show_to_all": false
      },
      "195921": {
        "id": 195921,
        "active": true,
        "required": false,
        "applies_to": "timesheet",
        "type": "free-form",
        "short_code": "m",
        "regex_filter": "",
        "name": "Mood",
        "last_modified": "2018-03-27T16:13:35+00:00",
        "created": "2018-03-27T16:13:35+00:00",
        "ui_preference": "text_box_with_suggest",
        "required_customfields": [ ],
        "show_to_all": true
      },
      "195919": {
        "id": 195919,
        "active": true,
        "required": false,
        "applies_to": "timesheet",
        "type": "managed-list",
        "short_code": "w",
        "regex_filter": "",
        "name": "Work Type",
        "last_modified": "2018-03-27T16:13:35+00:00",
        "created": "2018-03-27T16:13:35+00:00",
        "ui_preference": "drop_down",
        "required_customfields": [ ],
        "show_to_all": true
      }
    }
  },
  "more": false
}

Retrieves a list of all customfields associated with your company, with optional filters to narrow down the results.

HTTP Request

get https://rest.tsheets.com/api/v1/customfields

Filter Parameters


ids optional	Int	Comma separated list of one or more customfield ids you'd like to filter on. Only customfields with an id set to one of these values will be returned. If omitted, all customfields matching other specified filters are returned.
active optional	String	'yes', 'no', or 'both'. Default is 'yes'.
applies_to optional	String	'timesheet', 'user', 'jobcode', or 'all'. Default is 'timesheet'.
value_type optional	String	'managed-list', 'free-form', or 'both'. Default is 'both'.
modified_before optional	String	Only customfields modified before this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
modified_since optional	String	Only customfields modified since this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
supplemental_data optional	String	'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
~~per_page~~ ~~optional~~	~~Int~~	**Deprecated. Use `limit` for new code.** Represents how many results you'd like to retrieve per request. Default is 50. Max is 50. If a value over 50 is provided, it is ignored, and the max is used.
limit optional	Int	Represents how many results you'd like to retrieve per request. Default is 200. Max is 200. If present, this value must be: an integer, greater than zero, and not greater than 200. Setting `limit` less than 1 or greater than 200 will result in an error.
page optional	Int	Represents the page of results you'd like to retrieve. Default is 1.

Create Custom Fields

Example: Create a new customfield.

Request Body

{
 "data":
  [
    {
      "name": "Vehicle Number",
      "required": true,
      "active": true,
      "applies_to": "timesheet",
      "type": "managed-list",
      "show_to_all": true,
      "short_code": "vin"
    }
  ]
}

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/customfields \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/customfields");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfields")
Dim request = New RestRequest(Method.POST)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfields")
  .post(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00",
  "method": "POST",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/customfields',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfields');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfields")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfields"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfields"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfields")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="https://rest.tsheets.com/api/v1/customfields"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfields": {
      "1": {
        "_status_code": 200,
        "_status_message": "Created",
        "id": 1234567890,
        "name": "Vehicle Number",
        "required": true,
        "active": true,
        "applies_to": "timesheet",
        "type": "managed-list",
        "short_code": "vin",
        "regex_filter": "",
        "show_to_all": true,
        "last_modified": "2019-02-10T20:40:41+00:00",
        "created": "2019-02-10T20:40:41+00:00",
        "ui_preference": "dropdown",
        "required_customfields": [],
        "show_to_all": true
      }
    }
  }
}

Add one or more customfields.

HTTP Request

post https://rest.tsheets.com/api/v1/customfields

Properties

Pass an array of customfield objects as the value to a 'data' property (see example).


name required	String	The name of this customfield.
required optional	Boolean	Default: `false`. If true, a non-null value must be selected for this customfield when it appears on a timesheet.
active optional	Boolean	Default: `true`. If false, this `customfield` is considered archived and will not be visible or usable.
applies_to required	String	Default: `timesheet`. Allowed values: 'timesheet'. Specify that this `customfield` should appear on timesheets (additional customfield types may be supported in the future).
type required	String	Allowed values: 'managed-list', 'free-form'. A managed-list customfield is intended to be displayed as a dropdown list, where each 'option' is a customfielditem. A 'free-form' customfield supports text entry and does not require a collection of customfielditems to accompany it.
show_to_all optional	Boolean	Default: `false`. Declares whether this customfield should be shown on timesheets regardless of the jobcode chosen. If false, it will only appear when the chosen jobcode for a timesheet has been associated with this field.
short_code optional	String	Default: `""` (none). This is a shortened code or alias that is associated with the customfield. It may only consist of letters and numbers. If not provided, an alias will be auto-generated.

For a full list of the properties that may be set on a customfield, see The Custom Field Object.

Status Codes

Each customfield that is created will come back with a _status_code and _status_message that will indicate whether the customfield was created successfully. If there was a problem creating a customfield, there may also be an additional field, _status_extra, which will contain more details about the failure.


`200`	OK. customfield was created successfully.
`417`	Expectation Failed. Something was wrong or missing with the properties supplied for this customfield. See the `_status_extra` value for more detail.

The maximum batch size is 50 customfields. If exceeded, a 413: Request entity too large HTTP response will be returned.

Update Custom Fields

Example: Change some information for each of these customfields. The first customfield will have its name changed. The second field is being archived by setting active to false.

Request Body

{
 "data":
  [
    {
      "id":19142,
      "name":"Vehicle"
    },
    {
      "id":21889,
      "active":false,
    }
  ]
}

Request

curl -X PUT \
  https://rest.tsheets.com/api/v1/customfields \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/customfields");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfields")
Dim request = New RestRequest(Method.PUT)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfields")
  .put(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfields?modified_since=2018-01-01T00:00:00%2B00:00",
  "method": "PUT",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'PUT',
  url: 'https://rest.tsheets.com/api/v1/customfields',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfields');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfields")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfields"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("PUT", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfields"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("PUT", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "http://rest.tsheets.com/api/v1/customfields")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="http://rest.tsheets.com/api/v1/customfields"; 

$client->PUT($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfields": {
      "1": {
        "_status_code": 200,
        "_status_message": "Updated",
        "id": 19142,
        "name": "Vehicle",
        "required": true,
        "active": true,
        "applies_to": "timesheet",
        "type": "managed-list",
        "short_code": "vin",
        "regex_filter": "",
        "show_to_all": true,
        "last_modified": "2019-11-03T16:05:10+00:00",
        "created": "2019-02-10T20:40:41+00:00",
        "ui_preference": "dropdown",
        "required_customfields": [],
        "show_to_all": true
      },
      "2": {
        "_status_code": 200,
        "_status_message": "Updated",
        "id": 21889,
        "name": "Task",
        "required": true,
        "active": false,
        "applies_to": "timesheet",
        "type": "managed-list",
        "short_code": "t",
        "regex_filter": "",
        "show_to_all": true,
        "last_modified": "2019-11-03T16:05:10+00:00",
        "created": "2019-02-10T20:40:41+00:00",
        "ui_preference": "dropdown",
        "required_customfields": [],
        "show_to_all": true
      }
    }
  }
}

Edit one or more customfields.

HTTP Request

put https://rest.tsheets.com/api/v1/customfields

Properties

Pass an array of customfield objects as the value to a 'data' property (see example).


id required	Int	Id of the customfield.

All other read-write properties defined on a Custom Field object may be passed in to the request with a new value in order to change it. If the value passed in is the same as it was previously, or if a particular property is not passed in at all, it will be ignored.

Note: The required_customfields property can't be modified through the API, but can be modified through the TSheets web app when logged in as an admin user.

Status Codes

Each customfield that is edited will come back with a _status_code and _status_message that will indicate whether the customfield was edited successfully. If there was a problem editing a customfield, there may also be an additional field, _status_extra, which will contain more details about the failure.


`200`	OK. Customfield was edited successfully.
`417`	Expectation Failed. Something was wrong or missing with the properties supplied for this customfield. See the `_status_extra` value for more detail.

The maximum batch size is 50 customfields. If exceeded, a 413: Request entity too large HTTP response will be returned.

Custom Field Items

A Custom Field Item represents an allowable value for a Custom Field Object of managed-list type. Each item represents a single drop-down choice displayed to the user in the web UI. The API provides methods to Create, Read, and Update custom field items. Set the active property false to archive (i.e. soft delete) a custom field item.

The Custom Field Item Object

Example

{
  "id": 3875655,
  "customfield_id": 143369,
  "active": true,
  "short_code": "JS",
  "name": "Jungle Safari",
  "last_modified": "2019-02-11T17:42:45+00:00",
  "required_customfields": []
}

Following is a list of the properties that belong to a customfield object, and a description of each.


id read-only	Int	Id of customfielditem.
customfield_id read-only	Int	Id for the customfield that this item belongs to.
name read-write	String	Name of the customfielditem.
short_code read-write	String	This is a short alias that is associated with the customfielditem. It may only consist of letters and numbers. Note: Custom Field Item `short_code` values must be unique for each TSheets account.
active read-write	Boolean	true or false. If false, the customfielditem is considered archived.
last_modified read-only	String	Date/time when this customfielditem was last modified, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
required_customfields read-only	Int[]	Ids of customfields that should be displayed when this customfielditem is selected on a timecard.

Retrieve Custom Field Items

Example: Retrieve a list of all active customfielditems belonging to the given customfield.

Request

curl "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditems',
  qs: {
    customfield_id: '195923',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditems');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'customfield_id' => '195923',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditems"

querystring = {
  "customfield_id":"195923",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Example: Retrieve a list of all customfielditems (active or deleted) belonging to the given customfield, and set pagination to 10 results/page.

Request

curl "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditems',
  qs: {
    customfield_id: '195923',
    limit: '10',
    active: 'both',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditems');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'customfield_id' => '195923',
  'limit' => '10',
  'active' => 'both',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditems"

querystring = {
  "customfield_id":"195923",
  "limit":"10",
  "active":"both",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&limit=10&active=both"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Example: Retrieve a list of customfielditems belonging to the given customfield and having given ids.

Request

curl "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditems',
  qs: {
    customfield_id: '195923',
    ids: '3875655,3875657',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditems');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'customfield_id' => '195923',
  'ids' => '3875655,3875657',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditems"

querystring = {
  "customfield_id":"195923",
  "ids":"3875655,3875657",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&ids=3875655,3875657"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Example: Retrieve a list of customfielditems belonging to a given customfield that have been modified since a particular date.

Request

curl "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditems',
  qs: {
    customfield_id: '195923',
    modified_since: '2018-01-01T00:00:00-06:00',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditems');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'customfield_id' => '195923',
  'modified_since' => '2018-01-01T00:00:00-06:00',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditems"

querystring = {
  "customfield_id":"195923",
  "modified_since":"2018-01-01T00:00:00-06:00",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&modified_since=2018-01-01T00:00:00-06:00"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Example: Retrieve a list of customfielditems belonging to a given customfield and using the name wildcard, end in the given string.

Request

curl "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditems',
  qs: {
    customfield_id: '195923',
    name: '*ate',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditems');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'customfield_id' => '195923',
  'name' => '*ate',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditems"

querystring = {
  "customfield_id":"195923",
  "name":"*ate",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditems": {
      "1080235": {
        "id": 1080235,
        "customfield_id": 195923,
        "active": true,
        "short_code": "",
        "name": "Bazooka",
        "last_modified": "2018-03-27T16:13:35+00:00",
        "required_customfields": [ ]
      },
      "1080237": {
        "id": 1080237,
        "customfield_id": 195923,
        "active": true,
        "short_code": "",
        "name": "Shovel",
        "last_modified": "2018-03-27T16:13:35+00:00",
        "required_customfields": [ ]
      },
      "1080233": {
        "id": 1080233,
        "customfield_id": 195923,
        "active": true,
        "short_code": "",
        "name": "Tractor",
        "last_modified": "2018-03-27T16:13:35+00:00",
        "required_customfields": [ ]
      }
    }
  },
  "more": false,
  "supplemental_data": {
    "customfields": {
      "195923": {
        "id": 195923,
        "active": true,
        "required": true,
        "applies_to": "timesheet",
        "type": "managed-list",
        "short_code": "e",
        "regex_filter": "",
        "name": "Equipment",
        "last_modified": "2018-04-04T16:04:00+00:00",
        "created": "2018-03-27T16:13:35+00:00",
        "ui_preference": "drop_down",
        "required_customfields": [ ],
        "show_to_all": true
      }
    }
  }
}

Retrieves a list of all customfielditems associated with a customfield, with optional filters to narrow down the results.

HTTP Request

get https://rest.tsheets.com/api/v1/customfielditems

Filter Parameters


customfield_id required	Int	Id of the custom field whose items you'd like to list.
ids optional	Int	Comma separated list of one or more customfielditem ids you'd like to filter on. Only customfielditems with an `id` set to one of these values will be returned. If omitted, all customfielditems matching other specified filters are returned.
active optional	String	'yes', 'no', or 'both'. Default is 'yes'. If a customfielditem is active, it is available for selection during time entry.
name optional	String	* will be interpreted as a wild card. Starts matching from the beginning of the string.
modified_before optional	String	Only customfielditems modified before this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
modified_since optional	String	Only customfielditems modified since this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
supplemental_data optional	String	'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
~~per_page~~ ~~optional~~	~~Int~~	**Deprecated. Use `limit` for new code.** Represents how many results you'd like to retrieve per request. Default is 50. Max is 50. If a value over 50 is provided, it is ignored, and the max is used.
limit optional	Int	Represents how many results you'd like to retrieve per request. Default is 200. Max is 200. If present, this value must be: an integer, greater than zero, and not greater than 200. Setting `limit` less than 1 or greater than 200 will result in an error.
page optional	Int	Represents the page of results you'd like to retrieve. Default is 1.

Create Custom Field Items

Example: Create two new customfielditems. One succeeds. The other fails because of a duplicate short_code on an existing customfielditem.

Request Body

{
 "data":
  [
    {
      "name":"ServiceItem1",
      "customfield_id":"19142",
      "short_code":"c1"
    },
    {
      "name":"ServiceItem2",
      "customfield_id":"19142",
      "short_code":"c1"
    }
  ]
}

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/customfielditems \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditems");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditems")
Dim request = New RestRequest(Method.POST)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditems")
  .post(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate",
  "method": "POST",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/customfielditems',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditems');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditems")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditems"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditems"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditems")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="https://rest.tsheets.com/api/v1/customfielditems"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditems": {
      "1": {
        "_status_code": 200,
        "_status_message": "Created",
        "id": 3085864,
        "customfield_id": 19142,
        "active": true,
        "short_code": "c1",
        "name": "ServiceItem1"
      },
      "2": {
        "_status_code": 417,
        "_status_message": "Expectation Failed",
        "_status_extra": "Oops! The name or alias conflicts with another item named \"ServiceItem1\". Try choosing another name\/alias or deleting the other conflicting item first",
        "name": "ServiceItem2"
      }
    }
  },
  "supplemental_data": {
    "customfields": {
      "19142": {
        "id": 19142,
        "required": true,
        "type": "timesheet",
        "ui_preference": "managed-list",
        "short_code": "cf1",
        "regex_filter": "",
        "name": "Custom Field 1",
        "last_modified": "2018-07-23T23:09:14+00:00",
        "created": "2018-07-23T23:09:14+00:00"
      }
    }
  }
}

Add one or more customfielditems to a customfield.

HTTP Request

post https://rest.tsheets.com/api/v1/customfielditems

Properties

Pass an array of customfielditem objects as the value to a 'data' property (see example).


name required	String	Name of the customfielditem.
customfield_id required	Int	The id of the customfield you want this item to belong to.

For a full list of the properties that may be set on a customfielditem, see The Custom Field Item Object.

Status Codes

Each customfielditem that is created will come back with a _status_code and _status_message that will indicate whether the customfielditem was created successfully. If there was a problem creating a customfielditem, there may also be an additional field, _status_extra, which will contain more details about the failure.


`200`	OK. customfielditem was created successfully.
`417`	Expectation Failed. Something was wrong or missing with the properties supplied for this customfielditem. See the `_status_extra` value for more detail.

The maximum batch size is 50 customfielditems. If exceeded, a 413: Request entity too large HTTP response will be returned.

Update Custom Field Items

Example: Change some information for each of these customfielditems.

Request Body

{
 "data":
  [
    {
      "id":3085064,
      "customfield_id":19142,
      "active":true,
      "short_code":"por",
      "name":"Porsche"
    },
    {
      "id":3085066,
      "customfield_id":19142,
      "active":false,
      "short_code":"merc",
      "name":"Mercruiser"
    }
  ]
}

Request

curl -X PUT \
  https://rest.tsheets.com/api/v1/customfielditems \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditems");
var request = new RestRequest(Method.PUT);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditems")
Dim request = New RestRequest(Method.PUT)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditems")
  .put(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=195923&name=*ate",
  "method": "PUT",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'PUT',
  url: 'https://rest.tsheets.com/api/v1/customfielditems',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditems');
$request->setMethod(HTTP_METH_PUT);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditems")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditems"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("PUT", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditems"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("PUT", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "http://rest.tsheets.com/api/v1/customfielditems")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "PUT"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="http://rest.tsheets.com/api/v1/customfielditems"; 

$client->PUT($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditems": {
      "1": {
        "_status_code": 200,
        "_status_message": "Updated",
        "id": 3085064,
        "customfield_id": 19142,
        "active": true,
        "short_code": "por",
        "name": "Porsche"
      },
      "2": {
        "_status_code": 200,
        "_status_message": "Updated",
        "id": 3085066,
        "customfield_id": 19142,
        "active": false,
        "short_code": "merc",
        "name": "Mercruiser"
      }
    }
  },
  "supplemental_data": {
    "customfields": {
      "19142": {
        "id": 19142,
        "required": true,
        "type": "timesheet",
        "ui_preference": "managed-list",
        "short_code": "cf1",
        "regex_filter": "",
        "name": "Custom Field 1",
        "last_modified": "2018-07-23T23:09:14+00:00",
        "created": "2018-07-23T23:09:14+00:00",
        "required_customfields": [],
        "show_to_all": false
      }
    }
  }
}

Edit one or more customfielditems for a customfield.

HTTP Request

put https://rest.tsheets.com/api/v1/customfielditems

Properties

Pass an array of customfielditem objects as the value to a 'data' property (see example).


id required	Int	Id of the customfielditem.

All other properties defined on a Custom Field Item object may be passed in to the request with a new value in order to change it. If the value passed in is the same as it was previously, or if a particular property is not passed in at all, it will be ignored.

Status Codes

Each customfielditem that is edited will come back with a _status_code and _status_message that will indicate whether the customfielditem was edited successfully. If there was a problem editing a customfielditem, there may also be an additional field, _status_extra, which will contain more details about the failure.


`200`	OK. Customfielditem was edited successfully.
`417`	Expectation Failed. Something was wrong or missing with the properties supplied for this customfielditem. See the `_status_extra` value for more detail.

The maximum batch size is 50 customfielditems. If exceeded, a 413: Request entity too large HTTP response will be returned.

Custom Field Item Filters

The Item Filter Object

Example

{
  "id": 861013,
  "active": true,
  "applies_to": "jobcodes",
  "applies_to_id": 1883683,
  "customfielditem_id": 703671,
  "customfield_id": 117893,
  "last_modified": "2018-07-17T23:40:51+00:00"
}

Following is a list of the properties that belong to a customfielditem_filter object, and a description of each.


id read-only	Int	Id of `customfielditem_filter`.
customfield_id read-write	Int	Id for the customfield that this filter belongs to.
customfielditem_id read-write	Int	Id for the customfielditem that this filter belongs to.
applies_to read-write	String	Entity type this filter relates to. Together with `applies_to_id`, determines what this filtered item relates to. The possible values are: 'jobcodes', 'users', or 'groups'. For example: If this value was 'jobcodes' then the `applies_to_id` value would indicate which jobcode this filter referred to. If requested, the supplemental data will also contain this jobcode.
applies_to_id read-write	Int	The jobcode, user, or group that this filter relates to. Together with `applies_to`, determines what this filtered item relates to. For example: If the value of the `applies_to field` was 'jobcodes' this value would indicate which jobcode this filter referred to. If requested, the supplemental data will also contain this jobcode.
active read-write	Boolean	true or false. If false, this `customfielditem_filter` is considered archived or deleted.
last_modified read-only	String	Date/time when this `customfielditem_filter` was last modified, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).

Retrieve Item Filters

Example: Retrieve a list of all customfielditem_filters modified since a given date/time.

Request

curl "https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditem_filters',
  qs: {
    modified_since: '2018-07-17T00:00:00-00:00',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditem_filters');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'modified_since' => '2018-07-17T00:00:00-00:00',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditem_filters"

querystring = {
  "modified_since":"2018-07-17T00:00:00-00:00",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditem_filters": {
      "861013": {
        "id": 861013,
        "active": true,
        "applies_to": "jobcodes",
        "applies_to_id": 1883683,
        "customfielditem_id": 703671,
        "customfield_id": 117893,
        "last_modified": "2018-07-17T23:40:51+00:00"
      },
      "861015": {
        "id": 861015,
        "active": true,
        "applies_to": "users",
        "applies_to_id": 933849,
        "customfielditem_id": 703671,
        "customfield_id": 117893,
        "last_modified": "2018-07-17T23:40:51+00:00"
      },
      "861017": {
        "id": 861017,
        "active": true,
        "applies_to": "groups",
        "applies_to_id": 90443,
        "customfielditem_id": 703671,
        "customfield_id": 117893,
        "last_modified": "2018-07-17T23:40:51+00:00"
      }
    }
  },
  "more": false,
  "supplemental_data": {
    "jobcodes": {
      "1883683": {
        "id": 1883683,
        "active": true,
        "parent_id": 0,
        "assigned_to_all": true,
        "type": "pto",
        "billable": false,
        "billable_rate": 0,
        "short_code": "",
        "name": "Holiday",
        "created": "2017-08-28T15:57:15+0000",
        "last_modified": "2018-07-17T23:40:51+0000",
        "has_children": false,
        "required_customfields": [ ],
        "filtered_customfielditems": {
          "117893": [
            703671
          ]
        },
        "locations": [ ]
      }
    },
    "customfields": {
      "117893": {
        "id": 117893,
        "active": true,
        "name": "Fruit",
        "short_code": "fr",
        "required": 0,
        "applies_to": "timesheet",
        "type": "managed-list",
        "regex_filter": "",
        "last_modified": "2018-07-17T21:35:07+00:00",
        "created": "2017-08-30T16:12:52+00:00",
        "ui_preference": "drop_down",
        "required_customfields": [ ]
      }
    },
    "customfielditems": {
      "703671": {
        "id": 703671,
        "active": true,
        "name": "banana",
        "short_code": "",
        "customfield_id": 117893,
        "last_modified": "2018-07-17T21:35:07+00:00",
        "required_customfields": [ ]
      }
    },
    "users": {
      "933849": {
        "id": 933849,
        "first_name": "Mary",
        "last_name": "Samsonite",
        "group_id": 0,
        "active": true,
        ...
      }
    },
    "groups": {
      "90443": {
        "id": 90443,
        "active": true,
        "name": "customfielditem_filter_test_group",
        ...
      }
    }
  }
}

Retrieves a list of all customfielditem_filters associated with a jobcode, user, or group with options to narrow down the results.

Custom field item filters are used to limit the choices that should be made available for selecting customfielditems for a particular customfield based on a user or selected jobcode. If filtered items exist for a given user, user's group, or jobcode, the choices for the indicated customfield should be limited to those customfielditems only.

Please note that users can belong to groups and that groups can have filtered items. When requesting filtered items for a user, you can pass the 'include_user_group' option to return the customfielditem_filters for both the user and their assigned group.

HTTP Request

get https://rest.tsheets.com/api/v1/customfielditem_filters

Filter Parameters


jobcode_id optional	Int	Limits the returned filters to only those for the specified jobcode_id.
user_id optional	Int	Limits the returned filters to only those for the specified `user_id`. You can also include items for this user's group automatically if you include the 'include_user_group' parameter.
group_id optional	Int	Limits the returned filters to only those for the specified `group_id`.
include_user_group optional	Boolean	true or false. If a `user_id` is supplied, will return filters for that user's group as well.
include_jobcode_filters optional	Boolean	true or false. If a `user_id` is supplied, will additionally return jobcode filters.
ids optional	Int	Comma separated list of one or more `customfielditem_filter` ids you'd like to filter on. Only `customfielditem_filters` with an id set to one of these values will be returned. If omitted, all `customfielditem_fields` matching other specified filters are returned.
active optional	String	'yes', 'no', or 'both'. Default is 'yes'. If a `customfielditem_filter` is inactive, it can be safely ignored.
modified_before optional	String	Only `customfielditem_filters` modified before this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
modified_since optional	String	Only `customfielditem_filters` modified since this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
supplemental_data optional	String	'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
~~per_page~~ ~~optional~~	~~Int~~	**Deprecated. Use `limit` for new code.** Represents how many results you'd like to retrieve per request. Default is 50. Max is 50. If a value over 50 is provided, it is ignored, and the max is used.
limit optional	Int	Represents how many results you'd like to retrieve per request. Default is 200. Max is 200. If present, this value must be: an integer, greater than zero, and not greater than 200. Setting `limit` less than 1 or greater than 200 will result in an error.
page optional	Int	Represents the page of results you'd like to retrieve. Default is 1.

Create Item Filters

Example: Create two new customfielditemfilters. One succeeds. The other fails because of an invalid applies_to.

Request Body

{
 "data":
  [
    {
      "customfield_id": "1",
      "customfielditem_id": "1",
      "applies_to": "jobcodes",
      "applies_to_id": "1",
      "active": true
    },
    {
      "customfield_id": "1",
      "customfielditem_id": "1",
      "applies_to": "invalid-applies-to",
      "applies_to_id": "2",
      "active": true
    }
  ]
}

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/customfielditemfilters \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditemfilters");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditemfilters")
Dim request = New RestRequest(Method.POST)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditemfilters")
  .post(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00",
  "method": "POST",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/customfielditemfilters',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditemfilters');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditemfilters")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditemfilters"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditemfilters"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditemfilters")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="https://rest.tsheets.com/api/v1/customfielditemfilters"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditems": {
      "1": {
        "_status_code": 200,
        "_status_message": "Created",
        "id": 101,
        "customfield_id": 1,
        "customfielditem_id": 1,
        "applies_to": "jobcodes",
        "applies_to_id": 1
        "active": true
      },
      "2": {
        "_status_code": 417,
        "_status_message": "Expectation Failed",
        "_status_extra": "The applies_to value must be one of the following: jobcodes, users, groups.",
        "customfield_id": "1",
        "customfielditem_id": "1",
        "applies_to": "invalid-applies-to",
        "applies_to_id": "2",
        "active": true
      }
    }
  },
  "supplemental_data": {
    "jobcodes": {...},
    "customfields": {...},
    "customfielditems": {...}
  }
}

Add one or more customfielditemfilters.

HTTP Request

post https://rest.tsheets.com/api/v1/customfielditem_filters

Properties

Pass an array of customfielditemfilter objects as the value to a 'data' property (see example).


customfield_id required	Int	The id of the customfield this filter to belong to.
customfielditem_id required	Int	The id of the customfielditem this filter to belong to.
applies_to read-write	String	Entity type this filter relates to. Together with `applies_to_id`, determines what this filtered item relates to. The possible values are: 'jobcodes', 'users', or 'groups'. For example: If this value was 'jobcodes' then the `applies_to_id` value would indicate which jobcode this filter referred to. If requested, the supplemental data will also contain this jobcode.
applies_to_id read-write	Int	The jobcode, user, or group that this filter relates to. Together with `applies_to`, determines what this filtered item relates to. For example: If the value of the `applies_to field` was 'jobcodes' this value would indicate which jobcode this filter referred to. If requested, the supplemental data will also contain this jobcode.
active read-write	Boolean	true or false. If false, this `customfielditem_filter` is considered archived or deleted.

For a full list of the properties that may be set on a customfielditemfilter, see The Item Filter Object.

Status Codes

Each customfielditemfilter that is created will come back with a _status_code and _status_message that will indicate whether the customfielditemfilter was created successfully. If there was a problem creating a customfielditemfilter, there may also be an additional field, _status_extra, which will contain more details about the failure.


`200`	OK. customfielditemfilter was created successfully.
`417`	Expectation Failed. Something was wrong or missing with the properties supplied for this customfielditemfilter. See the `_status_extra` value for more detail.

The maximum batch size is 50 customfielditemfilters. If exceeded, a 413: Request entity too large HTTP response will be returned.

Update Item Filters

Example: Update two customfielditemfilters. One succeeds. The other fails because of an invalid applies_to.

Request Body

{
 "data":
  [
    {
      "id": 101,
      "active": "no"
    },
    {
      "id": 102,
      "applies_to": "invalid-applies-to"
    }
  ]
}

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/customfielditemfilters \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditemfilters");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditemfilters")
Dim request = New RestRequest(Method.POST)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditemfilters")
  .post(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditem_filters?modified_since=2018-07-17T00:00:00-00:00",
  "method": "POST",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/customfielditemfilters',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditemfilters');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditemfilters")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditemfilters"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditemfilters"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditemfilters")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="https://rest.tsheets.com/api/v1/customfielditemfilters"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditems": {
      "1": {
        "id": 101,
        "customfield_id": 2,
        "customfielditem_id": 3,
        "applies_to": "jobcodes",
        "applies_to_id": 1
        "active": true,
        "last_modified": "2022-02-24T21:45:19+00:00",
        "_status_code": 200,
        "_status_message": "Updated",
      },
      "2": {
        "id": 102,
        "applies_to": "invalid_applies_to",
        "_status_code": 417,
        "_status_message": "Expectation Failed",
        "_status_extra": "The applies_to value must be one of the following: jobcodes, users, groups."
      }
    }
  },
  "supplemental_data": {
    "jobcodes": {...},
    "customfields": {...},
    "customfielditems": {...}
  }
}

Edit one or more customfielditemfilters.

HTTP Request

put https://rest.tsheets.com/api/v1/customfielditem_filters

Properties

Pass an array of customfielditemfilter objects as the value to a 'data' property (see example).


id required	Int	Id of the customfielditemfilter.

All other read-write properties defined on an Item Filter object may be passed in to the request with a new value in order to change it. If the value passed in is the same as it was previously, or if a particular property is not passed in at all, it will be ignored.

Status Codes


`200`	OK. customfielditemfilter was created successfully.
`417`	Expectation Failed. Something was wrong or missing with the properties supplied for this customfielditemfilter. See the `_status_extra` value for more detail.

The maximum batch size is 50 customfielditemfilters. If exceeded, a 413: Request entity too large HTTP response will be returned.

Custom Field Item Jobcode Filters

The Jobcode Filter Object

Example

{
  "id": 3429889,
  "last_modified": "2018-07-17T23:40:51+00:00",
  "filtered_customfielditems": {
    "266131": [
      "541863",
      "541869"
    ],
    "266129": [ ]
  }
}

Following is a list of the properties that belong to a customfielditem_jobcode_filter object, and a description of each.


id read-only	Int	Id of the jobcode to which the filters belong.
last_modified read-only	String	The latest date/time when one of the filtered items was updated, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
filtered_customfielditems read-write	Map	Each entity represents a custom field's active filters where the key is the custom field id and the value is an array of item ids to which the jobcode is assigned.

Retrieve Jobcode Filters

Example: Retrieve a list of all customfielditem_jobcode_filters modified since a given date/time.

Request

curl "https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters',
  qs: {
    modified_since: '2018-07-17T00:00:00-00:00',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'modified_since' => '2018-07-17T00:00:00-00:00',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters"

querystring = {
  "modified_since":"2018-07-17T00:00:00-00:00",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters?modified_since=2018-07-17T00:00:00-00:00"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditem_jobcode_filters": {
      "3429889": {
        "id": 3429889,
        "last_modified": "2018-07-17T23:40:51+00:00",
        "filtered_customfielditems": {
          "266131": [
            "541863",
            "541869"
          ],
          "266129": [ ]
        }
      },
      "3429509": {
        "id": 3429509,
        "last_modified": "2018-08-10T11:09:12+00:00",
        "filtered_customfielditems": {
          "266129": [
            "541892",
            "541899"
          ]
        }
      }
    }
  },
  "more": false
}

Retrieves a list of all customfielditem filters associated with a jobcode with options to narrow down the results.

Custom field item filters are used to limit the choices that should be made available for selecting customfielditems for a particular customfield based on a jobcode. If filtered items exist for a given jobcode the choices for the indicated customfield should be limited to those customfielditems only.

HTTP Request

get https://rest.tsheets.com/api/v1/customfielditem_jobcode_filters

Filter Parameters


jobcode_ids optional	Int	Comma separated list of one or more `jobcode` ids you'd like to filter on.
modified_before optional	String	Only customfielditem filters modified before this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
modified_since optional	String	Only customfielditem filters modified since this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
~~per_page~~ ~~optional~~	~~Int~~	**Deprecated. Use `limit` for new code.** Represents how many results you'd like to retrieve per request. Default is 50. Max is 50. If a value over 50 is provided, it is ignored, and the max is used.
limit optional	Int	Represents how many results you'd like to retrieve per request. Default is 200. Max is 200. If present, this value must be: an integer, greater than zero, and not greater than 200. Setting `limit` less than 1 or greater than 200 will result in an error.
page optional	Int	Represents the page of results you'd like to retrieve. Default is 1.

Custom Field Item User Filters

The User Filter Object

Example

{
  "id": 2064699,
  "type": "user",
  "last_modified": "2018-07-17T23:40:51+00:00",
  "filtered_customfielditems": {
    "272563": [
      "1884205",
      "1884207",
      "1884212"
    ],
    "272565": [ ]
  }
}

Following is a list of the properties that belong to a customfielditem_user_filter object, and a description of each.


id read-only	Int	Id of the user or group to which the filters belong.
type read-write	String	The entities filter type: 'user' or 'group'.
last_modified read-only	String	The latest date/time when one of the filtered items was updated, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
filtered_customfielditems read-write	Map	Each entity represents a custom field's active filters where the key is the custom field id and the value is an array of item ids to which the user is assigned.

Retrieve User Filters

Example: Retrieve a list of all customfielditem_user_filters modified since a given date/time.

Request

curl "https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/customfielditem_user_filters',
  qs: {
    modified_since: '2018-07-17T00:00:00-00:00',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/customfielditem_user_filters');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'modified_since' => '2018-07-17T00:00:00-00:00',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/customfielditem_user_filters"

querystring = {
  "modified_since":"2018-07-17T00:00:00-00:00",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/customfielditem_user_filters?modified_since=2018-07-17T00:00:00-00:00"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "customfielditem_user_filters": {
      "2064699": {
        "id": 2064699,
        "type": "user",
        "last_modified": "2018-07-17T23:40:51+00:00",
        "filtered_customfielditems": {
          "272563": [
            "1884205",
            "1884207",
            "1884212"
          ],
          "272565": [

          ]
        }
      },
      "2064699": {
        "id": 2064699,
        "type": "group",
        "last_modified": "2018-07-21T11:12:34+00:00",
        "filtered_customfielditems": {
          "272563": [
            "1884206",
            "1884209"
          ]
        }
      },
      "2064796": {
        "id": 2064796,
        "type": "user",
        "last_modified": "2018-08-10T11:09:12+00:00",
        "filtered_customfielditems": {
          "272563": [
            "1884206",
            "1884208"
          ]
        }
      }
    }
  },
  "more": false
}

Retrieves a list of all customfielditem filters associated with a user or group with options to narrow down the results.

Custom field item filters are used to limit the choices that should be made available for selecting customfielditems for a particular customfield based on a user. If filtered items exist for a given user or user's group the choices for the indicated customfield should be limited to those customfielditems only.

Please note that users can belong to groups and that groups can have filtered items. When requesting filtered items for a user, you can pass the 'include_user_group' option to return the customfielditem_user_filters for both the user and their assigned group.

HTTP Request

get https://rest.tsheets.com/api/v1/customfielditem_user_filters

Filter Parameters


user_id optional	Int	Limits the returned filters to only those for the specified `user_id`. You can also include items for this user's group automatically if you include the `include_user_group` parameter.
group_id optional	Int	Limits the returned filters to only those for the specified `group_id`.
include_user_group optional	Boolean	true or false. If a `user_id` is supplied, will return filters for that user's group as well.
modified_before optional	String	Only customfielditem filters modified before this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
modified_since optional	String	Only customfielditem filters modified since this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
~~per_page~~ ~~optional~~	~~Int~~	**Deprecated. Use `limit` for new code.** Represents how many results you'd like to retrieve per request. Default is 50. Max is 50. If a value over 50 is provided, it is ignored, and the max is used.
limit optional	Int	Represents how many results you'd like to retrieve per request. Default is 200. Max is 200. If present, this value must be: an integer, greater than zero, and not greater than 200. Setting `limit` less than 1 or greater than 200 will result in an error.
page optional	Int	Represents the page of results you'd like to retrieve. Default is 1.

Effective Settings

The Effective Settings Object

Example

{
  "general": {
    "settings": {
      "calculate_overtime": "1",
      "clockout_override": 1,
      "clockout_override_hours": 10,
      "clockout_override_notify_admin": 1,
      "clockout_override_notify_mgrs": 0,
      "daily_doubletime": "0",
      "daily_overtime": "0",
      "daily_regular_hours": 8,
      "date_locale": "us",
      "emp_panel": 1,
      "emp_panel_email": "0",
      "emp_panel_passwd": "0",
      "emp_panel_tz": "0",
      "employee_pto_entry": 0,
      "enable_timesheet_notes": "1",
      "hide_working_time": "0",
      "jc_label": "Job",
      "lunch_deduct": 0,
      "lunch_length": 1,
      "lunch_threshold": 9,
      "max_customfielditems": "-1",
      "max_jobcodes": "-1",
      "parent_clockin_display": 0,
      "payroll_end_date": "2018-09-28",
      "payroll_first_end_day": "1",
      "payroll_last_end_day": "16",
      "payroll_month_end_day": "1",
      "payroll_type": "biweekly",
      "pto_entry": 1,
      "pto_overtime": 0,
      "simple_clockin": 0,
      "time_format": 12,
      "timecard_fields": "JOBCODE,134913,143369,143377",
      "timeclock_label": "Time Clock",
      "timesheet_edit_notes_for_all_users": 0,
      "timesheet_notes_notify_admin": 0,
      "timesheet_notes_notify_mgrs": 0,
      "timesheet_notes_required": 0,
      "tz": "America/Denver",
      "week_start": 0,
      "weekly_regular_hours": "40"
    },
    "last_modified": "2019-02-11T17:45:18+00:00"
  },
  "alerts": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "approvals": {
    "settings": {
      "installed": "1"
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "breaks": {
    "settings": {
      "hide_pre_clockout_option": 0
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "dcaa": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "dialin": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "files": {
    "settings": {
      "installed": "1",
      "files_addon_app_discovery_notification": "1"
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "invoicing": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "location_aware": {
    "settings": {
      "installed": 1,
      "show_location": "1"
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "mobile_app_integrations": {
    "settings": {
      "installed": 1,
      "apps": {
        "expensify": {
          "triggers": {
            "TSMTriggerButton": {
              "id": 553,
              "active": true,
              "jobcode_ids": [
                0
              ],
              "android_playstore_uri": "org.me.mobiexpensifyg",
              "android_call_scheme": "http://mobile.expensify.com/SmartScan",
              "iphone_appstore_url": "https://itunes.apple.com/us/app/expensify-expense-reports/id471713959",
              "iphone_call_scheme": "http://mobile.expensify.com",
              "call_url_host": "SmartScan",
              "call_uri_format": "tag=%JOBCODE_NAME%&billable=%JOBCODE_BILLABLE%&email=%EMAIL%&callbackURL=%TSHEETS_RETURN_URL%",
              "callback_uri_format": ""
            }
          }
        }
      }
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "mobile_app_settings": {
    "settings": {
      "installed": "1",
      "location_tracking": "off",
      "mandatory_location_services": "0"
    },
    "last_modified": "2019-02-09T18:39:20+00:00"
  },
  "reminders": {
    "settings": {
      "installed": 1
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "projects": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "quickbooks": {
    "settings": {
      "installed": "1",
      "connector": "qbia_online",
      "connector_type": "payroll_single_sku",
      "two_way_sync_enabled_for_user": 0
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "restapi": {
    "settings": {
      "installed": "1"
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "rounding": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "schedule": {
    "settings": {
      "installed": "1",
      "business_hours_end": "17:00:00",
      "business_hours_start": "08:00:00",
      "drafted_first_schedule_event_occurred": "1",
      "manage_schedule_permission": "company",
      "published_first_schedule_event_occurred": "1",
      "trial_expiration_date": "2018-10-17",
      "view_schedule_permission": "company",
      "learning_step": "7",
      "employee_view": "company",
      "manager_view": "company"
    },
    "last_modified": "2019-02-09T18:03:55+00:00"
  },
  "sms": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "sounds": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "customfields": {
    "settings": {
      "maximum_allowed_timesheet_custom_fields": 6,
      "installed": "1"
    },
    "last_modified": "2019-02-10T20:34:10+00:00"
  },
  "time_entry": {
    "settings": {
      "installed": 1,
      "time_entry_method": "timecard",
      "mtc_format_time_display": "hhmm",
      "time_entry": 0,
      "timecard": 1,
      "weekly_timecard": 1,
      "timecard_daily": 0,
      "timesheet_edit": 0,
      "timesheet_map": 1,
      "pto_entry": 1,
      "timesheet_list_date_range_selection": "month",
      "timesheet_list_show_days_with_no_time": 0,
      "timesheet_list_wrap_text": 0,
      "timesheet_list_column_selection": "time,job,location,kiosk,attachments,notes",
      "timesheet_list_bottomless_scroll": 1,
      "mtc_combine_regular_timesheets": "0"
    },
    "last_modified": "2019-01-25T20:53:52+00:00"
  },
  "toodledo": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "twitter": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "xero": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  },
  "zenpayroll": {
    "settings": {
      "installed": 0
    },
    "last_modified": "2001-01-01T12:00:00+00:00"
  }
}

All combined, cascaded settings that apply to a given user are contained in the effective settings object.

The effective settings object consists of a series of sections. Each section contains a settings and a last_modified property. The settings property is a list of key/value pairs. The last_modified property is an ISO 8601-formatted timestamp. It gets updated any time a key/value pair within a section has changed.

Below is a list of the possible section headings.


general	General application settings
alerts	Settings for the Alerts Add-On
approvals	Settings for the Approvals Add-On
breaks	Settings for the Breaks Add-On
dcaa	Settings for the DCAA Compliance Add-On
dialin	Settings for the Dial-in Add-On
files	Settings for the Files Add-On
invoicing	Settings for the Invoicing Add-On
location_aware	Settings for the Location Aware Add-On
mobile_app_integrations	Settings for the Mobile App Integrations Add-On
mobile_app_settings	Settings for the Mobile App Settings Add-On
reminders	Settings for the Reminders Add-On
projects	Settings for the Projects Add-On
quickbooks	Settings for the Quickbooks Integration Add-On
restapi	Settings for the TSheets Rest API Add-On
rounding	Settings for the Timesheet Rounding Add-On
schedule	Settings for the Schedule Add-On
sms	Settings for the Text Messaging Add-On
sounds	Settings for the Sounds Add-On
customfields	Settings for the Advanced Tracking Add-On
time_entry	Settings for the Time Card Selector Add-On
toodledo	Settings for the Toodledo Add-On
twitter	Settings for the Twitter Add-On
xero	Settings for the Xero Integration Add-On
zenpayroll	Settings for the Zen Payroll Integration Add-On

For all sections except general, if not installed, the only setting will be installed with a value of 0. If installed, all applicable settings will be available.

Retrieve Effective Settings

Example: Retrieve a list of all effective settings for a specific user.

Request

curl "https://rest.tsheets.com/api/v1/effective_settings?user_id=1234" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/effective_settings?user_id=1234");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/effective_settings?user_id=1234")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/effective_settings?user_id=1234")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/effective_settings?user_id=1234",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/effective_settings',
  qs: {
    user_id: '1234',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/effective_settings');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'user_id' => '1234',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/effective_settings?user_id=1234")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/effective_settings"

querystring = {
  "user_id":"1234",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/effective_settings?user_id=1234"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/effective_settings?user_id=1234")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/effective_settings?user_id=1234"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Example: Retrieve a list of all effective settings modified since a specified date. Currently logged in user's id will be used since none is specified in the request.

Request

curl "https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/effective_settings',
  qs: {
    modified_since: '2018-03-01T00:00:00-0600',
  },
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/effective_settings');
$request->setMethod(HTTP_METH_GET);

$request->setQueryData(array(
  'modified_since' => '2018-03-01T00:00:00-0600',
));

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/effective_settings"

querystring = {
  "modified_since":"2018-03-01T00:00:00-0600",
}

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers, params=querystring)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/effective_settings?modified_since=2018-03-01T00:00:00-0600"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
  "results": {
    "effective_settings": {
      "general": {
        "settings": {
          "calculate_overtime": "1",
          "clockout_override": 1,
          "clockout_override_hours": 10,
          "clockout_override_notify_admin": 1,
          "clockout_override_notify_mgrs": 0,
          "daily_doubletime": "0",
          "daily_overtime": "0",
          "daily_regular_hours": 8,
          "date_locale": "us",
          "emp_panel": 1,
          "emp_panel_email": "0",
          "emp_panel_passwd": "0",
          "emp_panel_tz": "0",
          "employee_pto_entry": 0,
          "enable_timesheet_notes": "1",
          "hide_working_time": "0",
          "jc_label": "Job",
          "lunch_deduct": 0,
          "lunch_length": 1,
          "lunch_threshold": 9,
          "max_customfielditems": "-1",
          "max_jobcodes": "-1",
          "parent_clockin_display": 0,
          "payroll_end_date": "2018-09-28",
          "payroll_first_end_day": "1",
          "payroll_last_end_day": "16",
          "payroll_month_end_day": "1",
          "payroll_type": "biweekly",
          "pto_entry": 1,
          "pto_overtime": 0,
          "simple_clockin": 0,
          "time_format": 12,
          "timecard_fields": "JOBCODE,134913,143369,143377",
          "timeclock_label": "Time Clock",
          "timesheet_edit_notes_for_all_users": 0,
          "timesheet_notes_notify_admin": 0,
          "timesheet_notes_notify_mgrs": 0,
          "timesheet_notes_required": 0,
          "tz": "America/Denver",
          "week_start": 0,
          "weekly_regular_hours": "40"
        }
        "last_modified": "2018-04-05T19:19:45+00:00"
      },
      "alerts": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "approvals": {
        "settings": {
          "installed": "1"
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "breaks": {
        "settings": {
          "hide_pre_clockout_option": 0
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "dcaa": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "dialin": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "files": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "invoicing": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "mobile_app_integrations": {
        "settings": {
          "installed": 0,
          "apps": ""
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "mobile_app_settings": {
        "settings": {
          "installed": 1,
          "location_tracking": "optional",
          "mandatory_location_services": 0
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "reminders": {
        "settings": {
          "installed": 1
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "quickbooks": {
        "settings": {
          "installed": "1",
          "connector": "qbia_online",
          "two_way_sync_enabled_for_user": 0
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "restapi": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "rounding": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "schedule": {
        "settings": {
          "installed": "1",
          "business_hours_end": "17:00:00",
          "business_hours_start": "08:00:00",
          "manage_schedule_permission": "company",
          "trial_expiration_date": "2018-04-11",
          "view_schedule_permission": "company",
          "employee_view": "company",
          "manager_view": "company"
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "sms": {
        "settings": {
          "installed": 0,
          "email_notify": "1",
          "mobile_number": "2087231456",
          "sms_notify": "1"
        },
        "last_modified": "2018-03-27T16:13:35+00:00"
      },
      "sounds": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "customfields": {
        "settings": {
          "maximum_allowed_timesheet_custom_fields": 6,
          "installed": "1"
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "time_entry": {
        "settings": {
          "installed": 1,
          "time_entry_method": "timecard",
          "mtc_format_time_display": "hhmm",
          "time_entry": 0,
          "timecard": 1,
          "weekly_timecard": 1,
          "timecard_daily": 0,
          "timesheet_edit": 0,
          "timesheet_map": 1,
          "pto_entry": 1,
          "timesheet_list_date_range_selection": "week",
          "timesheet_list_show_days_with_no_time": 1,
          "timesheet_list_wrap_text": 0,
          "timesheet_list_column_selection": "time,job,location,kiosk,attachments,notes",
          "timesheet_list_bottomless_scroll": 0
        },
        "last_modified": "2018-04-04T19:42:03+00:00"
      },
      "toodledo": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "twitter": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "xero": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      },
      "zenpayroll": {
        "settings": {
          "installed": 0
        },
        "last_modified": "2001-01-01T12:00:00+00:00"
      }
    }
  }
}

Retrieves a list of all effective settings associated with a single user, with optional filters to narrow down the results.

HTTP Request

get https://rest.tsheets.com/api/v1/effective_settings

Filter Parameters


user_id optional	Int	User id for whom you'd like to retrieve effective settings. If none is specified, the currently logged in user's id will be used. Only effective settings that apply to this `user_id` will be returned. An admin will see more settings than a regular user will.
modified_before optional	String	Only sections with settings modified before this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
modified_since optional	String	Only sections with settings modified since this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).

Estimate Items

The Estimate Item Object

Example

{
    "id": 596193,
    "estimated_seconds": 46800,
    "estimate_id": 841513,
    "active": true,
    "created": "2019-09-11T16:24:14+00:00",
    "last_modified": "2019-09-11T16:24:14+00:00",
    "type": "tag_clouds",
    "type_id": 8680081
}

Following is a list of the properties that belong to an estimate item object, and a description of each.


id read-only	Int	ID of this estimate item.
estimated_seconds read-write	Int	The estimated number of seconds.
estimate_id write-once	Int	The estimate this estimate item belongs to.
active read-write	Boolean	True or false. If false, this estimate is considered deleted.
created read	String	Date/time when this estimate was created, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
last_modified read	String	Date/time when this estimate was last modified, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`).
type read-write	String	The estimate item type. One of 'none' or 'tag_clouds'. NOTE: A type of 'tag_clouds' should be 'customfields' instead. This will be corrected soon.
type_id read-write	Int	The customfielditem id if type is 'tag_clouds'.

Retrieve Estimate Items

Example: Retrieve a list of estimates based on the provided filter.

Request

curl "https://rest.tsheets.com/api/v1/estimate_items" \
  -H "Authorization: Bearer <TOKEN>" \

var client = new RestClient("https://rest.tsheets.com/api/v1/estimate_items");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <TOKEN>");
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/estimate_items")
Dim request = New RestRequest(Method.[GET])
request.AddHeader("Authorization", "Bearer <TOKEN>")
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/estimate_items")
  .get()
  .addHeader("Authorization", "Bearer <TOKEN>")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/estimate_items",
  "method": "GET",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
  }
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'GET',
  url: 'https://rest.tsheets.com/api/v1/estimate_items',
  headers: 
   {
     'Authorization': 'Bearer <TOKEN>',
   } };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/estimate_items');
$request->setMethod(HTTP_METH_GET);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
));

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/estimate_items")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <TOKEN>',

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/estimate_items"

payload = ""
headers = {
   'Authorization': "Bearer <TOKEN>",
  }

response = requests.request("GET", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/estimate_items"

  req, _ := http.NewRequest("GET", url, nil)

  req.Header.Add("Authorization", "Bearer <TOKEN>")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))
}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
]

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/estimate_items")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest, completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');

$url="https://rest.tsheets.com/api/v1/estimate_items"; 

$client->GET($url);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
    "results": {
        "estimate_items": {
            "596275": {
                "id": 596275,
                "estimated_seconds": 46800,
                "estimate_id": 841513,
                "active": true,
                "created": "2019-09-11T16:39:23+00:00",
                "last_modified": "2019-09-11T16:39:23+00:00",
                "type": "tag_clouds",
                "type_id": 8681617
            },
            "596276": {
                "id": 596275,
                "estimated_seconds": 60000,
                "estimate_id": 841513,
                "active": true,
                "created": "2019-09-12T16:00:00+00:00",
                "last_modified": "2019-09-13T15:32:21+00:00",
                "type": "tag_clouds",
                "type_id": 8681617
            }
        }
    },
    "supplemental_data": {
        "estimates": {
            "841513": {
                "id": 841513,
                "project_id": 1301813,
                "active": true,
                "created": "2019-09-11T16:24:14+00:00",
                "last_modified": "2019-09-11T16:24:14+00:00",
                "estimate_by": "customfields",
                "estimate_by__id": 1247597
            }
        }
    },
    "more": false
}

Retrieves a list of all estimate items associated with your company, with optional filters to narrow down the results.

HTTP Request

get https://rest.tsheets.com/api/v1/estimate_items

Filter Parameters


ids optional	Int	Comma-separated list of estimate item ids.
estimate_ids optional	Int	Comma-separated list of estimate ids associated with an estimate item.
active optional	String	'yes', 'no', or 'both'. Default is 'yes'.
modified_before optional	String	Only estimate items modified before this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`)
modified_since optional	String	Only estimate items modified since this date/time will be returned, in ISO 8601 format (`YYYY-MM-DDThh:mm:ss±hh:mm`)
supplemental_data optional	Boolean	'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
~~per_page~~ ~~optional~~	~~Int~~	**Deprecated. Use `limit` for new code.** Represents how many results you'd like to retrieve per request. Default is 50. Max is 50. If a value over 50 is provided, it is ignored, and the max is used.
limit optional	Int	Represents how many results you'd like to retrieve per request. Default is 200. Max is 200. If present, this value must be: an integer, greater than zero, and not greater than 200. Setting `limit` less than 1 or greater than 200 will result in an error.
page optional	Int	Represents the page of results you'd like to retrieve.

Create Estimate Items

Example: Create a new estimate item.

Request Body

{
    "data": [{
        "estimated_seconds": 46800,
        "estimate_id": 841513,
        "active": true,
        "type": "tag_clouds",
        "type_id": 8681617
    }]
}

Request

curl -X POST \
  https://rest.tsheets.com/api/v1/estimate_items \
  -H 'Authorization: Bearer <TOKEN>' \
  -H 'Content-Type: application/json' \
  -d '<REQUEST BODY>'

var client = new RestClient("https://rest.tsheets.com/api/v1/estimate_items");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <TOKEN>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);

Dim client = New RestClient("https://rest.tsheets.com/api/v1/estimate_items")
Dim request = New RestRequest(Method.POST)
request.AddHeader("Authorization", "Bearer <TOKEN>")
request.AddHeader("Content-Type", "application/json")
request.AddParameter("application/json", "<REQUEST BODY>", ParameterType.RequestBody);
Dim response As IRestResponse = client.Execute(request)

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "<REQUEST BODY>");
Request request = new Request.Builder()
  .url("https://rest.tsheets.com/api/v1/estimate_items")
  .post(body)
  .addHeader("Authorization", "Bearer <TOKEN>")
  .addHeader("Content-Type", "application/json")
  .build();

Response response = client.newCall(request).execute();

var settings = {
  "async": true,
  "crossDomain": true,
  "url": "https://rest.tsheets.com/api/v1/estimate_items",
  "method": "POST",
  "headers": {
    "Authorization", "Bearer <TOKEN>",
    "Content-Type", "application/json",
  },
  "processData": false,
  "data": "<REQUEST BODY>"
}

$.ajax(settings).done(function (response) {
  console.log(response);
});

var request = require("request");

var options = { method: 'POST',
  url: 'https://rest.tsheets.com/api/v1/estimate_items',
  headers: 
  { 
     'Authorization': 'Bearer <TOKEN>',
     'Content-Type': 'application/json',
  },
  body: '<REQUEST BODY>',
  json: true };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

<?php

$request = new HttpRequest();
$request->setUrl('https://rest.tsheets.com/api/v1/estimate_items');
$request->setMethod(HTTP_METH_POST);

$request->setHeaders(array(
  'Authorization' => 'Bearer <TOKEN>',
  'Content-Type' => 'application/json',
));

$request->setBody('<REQUEST BODY>');

try {
  $response = $request->send();

  echo $response->getBody();
} catch (HttpException $ex) {
  echo $ex;
}

require 'uri'
require 'net/http'

url = URI("https://rest.tsheets.com/api/v1/estimate_items")

http = Net::HTTP.new(url.host, url.port)

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <TOKEN>',
request["Content-Type"] = 'application/json',
request.body = "<REQUEST BODY>"

response = http.request(request)
puts response.read_body

import requests

url = "https://rest.tsheets.com/api/v1/estimate_items"

payload = "<REQUEST BODY>"
headers = {
    'Authorization': 'Bearer <TOKEN>',
    'Content-Type': 'application/json',
    }

response = requests.request("POST", url, data=payload, headers=headers)

print(response.text)

package main

import (
  "fmt"
  "strings"
  "net/http"
  "io/ioutil"
)

func main() {

  url := "https://rest.tsheets.com/api/v1/estimate_items"

  payload := strings.NewReader("<REQUEST BODY>")

  req, _ := http.NewRequest("POST", url, payload)

  req.Header.Add("Authorization", "Bearer <TOKEN>")
  req.Header.Add("Content-Type", "application/json")

  res, _ := http.DefaultClient.Do(req)

  defer res.Body.Close()
  body, _ := ioutil.ReadAll(res.Body)

  fmt.Println(res)
  fmt.Println(string(body))

}

import Foundation

let headers = [
   "Authorization": "Bearer <TOKEN>",
   "Content-Type": "application/json",
]
let parameters = <REQUEST BODY> as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(
  url: NSURL(string: "https://rest.tsheets.com/api/v1/estimate_items")! as URL,
  cachePolicy: .useProtocolCachePolicy,
  timeoutInterval: 10.0)

request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(
  with: request as URLRequest,
  completionHandler: {
    (data, response, error) -> Void in
    if (error != nil) {
      print(error)
    } else {
      let httpResponse = response as? HTTPURLResponse
      print(httpResponse)
    }
  }
)

dataTask.resume()

use REST::Client;

my $client = REST::Client->new();

$client->addHeader('Authorization', 'Bearer <TOKEN>');
$client->addHeader('Content-Type', 'application/json');

$req = '<REQUEST BODY>';

$url="https://rest.tsheets.com/api/v1/estimate_items"; 

$client->POST($url, $req);
print $client->responseContent();
print $client->responseHeader('ResponseHeader');

Response Format

200 OK

{
    "results": {
        "estimate_items": {
            "1": {
                "_status_code": 200,
                "_status_message": "Created",
                "id": 596275,
                "estimated_seconds": 46800,
                "estimate_id": 841513,
                "active": true,
                "created": "2019-09-11T16:39:23+00:00",
                "last_modified": "2019-09-11T16:39:23+00:00",
                "type": "tag_clouds",
                "type_id": 8681617
            }
        }
    },
    "supplemental_data": {
        "estimates": {
            "841513": {
                "id": 841513,
                "project_id": 1301813,
                "active": true,
                "created": "2019-09-11T16:24:14+00:00",
                "last_modified": "2019-09-11T16:24:14+00:00",
                "estimate_by": "customfields",
                "estimate_by__id": 1247597
            }
        }
    }
}

Add one or more estimate items to your company.

HTTP Request

post https://rest.tsheets.com/api/v1/estimate_items

Properties

Pass an array of estimate item objects as the value to a 'data' property (see example).


estimate_id required	Int	The estimate this estimate item belongs to.
type required	String	The estimate type. One of 'none' or 'tag_clouds'.
type_id optional	Int	The customfielditem id if type is 'tag_clouds'.
estimated_seconds optional	Int	The estimated number of seconds.

For a full list of properties that may be set on an estimate item, see The Estimate Item Object.

Introduction

Getting Started

Postman Collection

1) Open the TSheets Postman Collection

2) Configure the Postman Environment

3) Explore the API

Base URL

Contribute

Request Throttling

Response Size Limit

SDK's & Helper Libraries

Full SDK's

Helper Libraries

Connection Count Information

Getting Help

Authentication

OAuth2.0

Obtaining a Token

Step 1. Authorization Request

HTTP Request

Parameters

Step 2. Access Token Request

HTTP Request

Parameters

Make Requests With the Access Token

Storing a Token

Refreshing an Access Token

HTTP Request

Parameters

Request Formats

Retrieve resources with the HTTP GET Method

Create new resources with the HTTP POST Method

Update existing resources with the HTTP PUT Method

Delete resources with the HTTP DELETE Method

Possible HTTP Response Status Codes

2xx response codes

3xx response codes

4xx response codes

5xx response codes

_status_code's in the Response Body

Response Formats

Exceptions

Tips & Suggestions

Requesting items that have changed since you last made a request to the API

Working with Jobcodes & Jobcode Assignments

Archiving objects no longer in use

Handling Supplemental Timesheet Data

Recipes for Some Common Workflows

Getting current status of a single user (whether on or off the clock)

Getting current status and totals of all users (or one) in compact format

Approving time

Running Payroll

Walkthroughs

Obtaining an API Access Token

1) Install the API App Feature Add-On

2) Select the API Add-On and click Install

3) Add a New Application

4) Enter API Application Details

5) Create a New Token

6) Capture the New Token Value for Use with the API

Current User

The Current User Object

Retrieve the Current User

HTTP Request

Parameters

Custom Fields

The Custom Field Object

Retrieve Custom Fields

HTTP Request

Filter Parameters

Create Custom Fields

HTTP Request

Properties

Status Codes

Update Custom Fields

HTTP Request

Properties

Status Codes

Custom Field Items

The Custom Field Item Object

`_status_code`'s in the Response Body