Optional fields

To reduce the number of roundtrips that might be required to fetch all related data for a given collection or resource (e.g. fetching a user and all their tags), the API supports a concept of optional fields. These fields are a comma separated list of field names that are supported as a URL parameter when making a request to fetch a resource or a resource collection.

curl -X GET https://api.rm.smartsheet.com/api/v1/users?fields=tags \
  -H "Content-Type: application/json"
  -H "auth: TOKEN"

Each field requested is included in the response as nested collections. The page size for these nested collections will be the same as the page size used for the parent API request.

{
  "data" : [
    {
      "id" : 1,
      "first_name" : "Tom",
      "last_name" : "Perera",
      "tags": {
        "data" : [
          { "id" : 1, "value" : "developer" },
          { "id" : 2, "value" : "javascript" },
        ],
        "paging" : {
          ...
        }
      }
    },
    ...
  ],
  "paging": {
    ...
  }
}

Multiple optional fields can be requested in a single API call like fields=f1,f2.