REST API: List Jobcodes

Last Updated: November 07, 2016

Description

Retrieves a list of all jobcodes associated with your company, with optional filters to narrow down the results. For a more efficient way of retrieving jobcodes assigned to a specific user, please see the jobcode-assignments endpoint.

Resource Information

HTTP Method GET
Endpoint https://rest.tsheets.com/api/v1/jobcodes
Authentication Token header required. See authentication section
Request format Everything is handled through the request uri on a GET.
Response format json
Response object Jobcode

Available Filters

ids:
optional
Integer. Comma separated list of one or more jobcode ids you'd like to filter on. Only jobcodes with an id set to one of these values will be returned. If omitted, all jobcodes matching other specified filters are returned.
parent_ids
optional
Integer. Default is -1 (meaning all jobcodes will be returned regardless of parent_id).

Comma separated list of one or more jobcode parent_ids you'd like to filter on. Only jobcodes with a parent_id set to one of these values will be returned. Additionally you can use 0 to get only the top-level jobcodes. Then get the id of any results with has_children=yes and feed that in as the value of parent_ids for your next request to get the 2nd level of jobcodes, and so on, to traverse an entire tree of jobcodes.

Use -1 to return all jobcodes regardless of parent_id; this is especially useful when combined with the modified_since filter. When parent_ids is -1, you'll have the jobcode records needed to trace each result back to it's top level parent in the supplemental_data section of the response.
type:
optional
String. regular, pto, unpaid_break, paid_break, or all. Default is regular.
active:
optional
String. 'yes', 'no', or 'both'. Default is 'yes'. If a jobcode is active, it is available for selection during time entry.
modified_before:
optional
String (ISO8601 format). Only jobcodes modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
optional
String (ISO8601 format). Only jobcodes modified since this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
supplemental_data:
optional
String. 'yes' or 'no'. Default is 'yes'. Indicates whether supplemental data should be returned.
per_page:
optional
Integer. Represents how many results you'd like to retrieve per request (page). Default is 50. Max is 50.
page:
optional
Integer. Represents the page of results you'd like to retrieve. Default is 1.

Examples

Retrieve a list of all active top-level jobcodes.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/jobcodes"

## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
 "results": {
  "jobcodes": {
   "17288279": {
    "id": 17288279,
    "parent_id": 0,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "asm",
    "name": "Assembly Line",
    "last_modified": "2013-07-12T21:13:14+00:00",
    "created": "2013-05-28T20:18:17+00:00"
   },
   "17288283": {
    "id": 17288283,
    "parent_id": 0,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "dev",
    "name": "Development Team",
    "last_modified": "2013-05-28T20:19:33+00:00",
    "created": "2013-05-28T20:19:33+00:00"
   }
  }
 },
 "more": false
}
    

Retrieve a list of all jobcodes (active or deleted) whose parent jobcode id is 235494. Set pagination to 10 results/page.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/jobcodes?parent_ids=235494&per_page=10&active=both"

## RESPONSE
HTTP/1.1 200 OK
Content-Type: application/json

{
 "results": {
  "jobcodes": {
   "17973881": {
    "id": 17973881,
    "parent_id": 17288281,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "mop",
    "name": "Mopping",
    "last_modified": "2013-07-12T21:13:46+00:00",
    "created": "2013-07-12T21:13:46+00:00"
   },
   "17973879": {
    "id": 17973879,
    "parent_id": 17288281,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": false,
    "billable_rate": 0,
    "short_code": "swp",
    "name": "Sweeping",
    "last_modified": "2013-07-12T21:13:38+00:00",
    "created": "2013-07-12T21:13:38+00:00"
   }
  }
 },
 "more": false,
 "supplemental_data": {
  "jobcodes": {
   "17288281": {
    "id": 17288281,
    "parent_id": 0,
    "assigned_to_all": false,
    "billable": false,
    "active": true,
    "type": "regular",
    "has_children": true,
    "billable_rate": 0,
    "short_code": "jan",
    "name": "Janatorial Work",
    "last_modified": "2013-07-12T21:13:02+00:00",
    "created": "2013-05-28T20:18:38+00:00"
   }
  }
 }
}
    

Retrieve a list of jobcodes with ids 12, 367, and 3489.

## REQUEST
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/jobcodes?ids=12,367,3489"

## RESPONSE
## (response would have the same layout as the above examples)
    

Retrieve a list of jobcodes that have been modified since Jan 1, 2013

## REQUEST
## Note that instead of a plus, we're using '%2B', the url-encoded equivalent - to prevent the + getting replaced by a space.
curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/jobcodes?modified_since=2013-01-01T00:00:00%2B00:00"

## RESPONSE
## (response would have the same layout as the above examples)