REST API: List Custom Field Items

Last Updated: November 07, 2016

Description

Retrieves a list of all customfielditems associated with a customfield, with optional filters to narrow down the results.

Resource Information

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

Available Filters

customfield_id:
required
Integer. Id of the custom field whose items you'd like to list.
ids:
optional
Integer. 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.
modified_before:
optional
String (ISO8601 format). Only customfielditems modified before this date/time will be returned (i.e. 2004-02-12T15:19:21+00:00).
modified_since:
optional
String (ISO8601 format). Only customfielditems 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 customfielditems belonging to the customfield whose id is 19142.

    ## REQUEST
    curl -H "Authorization: Bearer <Access-Token>" -i "https://rest.tsheets.com/api/v1/customfielditems?customfield_id=19142"

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

    {
        "results": {
            "customfielditems": {
                "3147808": {
                    "id": 3147808,
                    "customfield_id": 19476,
                    "active": true,
                    "short_code": "wha",
                    "name": "Whoa there doggy!",
                    "last_modified": "2013-08-19T22:32:22+00:00",
                    "required_customfields": []
                },
                "3263794": {
                    "id": 3263794,
                    "customfield_id": 19476,
                    "active": true,
                    "short_code": "kit",
                    "name": "Kitties",
                    "last_modified": "2013-10-30T18:47:10+00:00",
                    "required_customfields": []
                },
                "3263798": {
                    "id": 3263798,
                    "customfield_id": 19476,
                    "active": true,
                    "short_code": "sup",
                    "name": "Soy un perdedor",
                    "last_modified": "2013-09-26T22:30:52+00:00",
                    "required_customfields": []
                },
                "3350636": {
                    "id": 3350636,
                    "customfield_id": 19476,
                    "active": true,
                    "short_code": "",
                    "name": "Long Term Information",
                    "last_modified": "2013-10-30T19:26:09+00:00",
                    "required_customfields": []
                }
            }
        },
        "more": false,
        "supplemental_data": {
            "customfields": {
                "19476": {
                    "id": 19476,
                    "required": false,
                    "applies_to": "timesheet",
                    "type": "managed-list",
                    "short_code": "mlcf",
                    "regex_filter": "",
                    "name": "Managed List Custom Field",
                    "last_modified": "2014-03-06T21:15:02+00:00",
                    "created": "2013-08-08T19:22:15+00:00",
                    "ui_preference": "drop_down",
                    "required_customfields": []
                }
            }
        }
    }
    

Retrieve a list of all customfielditems (active or deleted) whose customfield_id is 19142. Set pagination to 10 results/page.

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

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

{
 "results": {
  "customfielditems": {
   "3085064": {
    "id": 3085064,
    "customfield_id": 19142,
    "active": true,
    "short_code": "",
    "name": "Item 1"
   },
   "3085066": {
    "id": 3085066,
    "customfield_id": 19142,
    "active": true,
    "short_code": "",
    "name": "Item 2"
   },
   "3085068": {
    "id": 3085068,
    "customfield_id": 19142,
    "active": false,
    "short_code": "",
    "name": "Item 3"
   }
  }
 },
 "more": false,
 "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": "2013-07-23T23:09:14+00:00",
    "created": "2013-07-23T23:09:14+00:00"
   }
  }
 }
}
    

Retrieve a list of customfielditems with a customfield_id 64 and ids 12, 367, and 3489.

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

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

Retrieve a list of customfielditems with a customfield_id of 44 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/customfielditems?customfield_id=44&modified_since=2013-01-01T00:00:00%2B00:00"

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