Sparse Fieldsets

Note: Sparse Fieldsets are only available with the Teamwork API V3. Supported Sparse Fieldsets are located under the Request Parameters section of each documented endpoint.

Sparse Fieldsets is a method to return only specific fields in the response on a per-type basis by including a fields[type] parameter. The type matches the object’s name and is listed alongside any desired attributes eg.fields[milestones]=id,name.

Example

A GET request is sent to: http://YOURSITE/projects/api/v3/milestones.json?include=projects

This returns a response of:

{
  "milestones": [
    {
      "id": 1,
      "name": "Milestone",
      "description": "",
      "deadline": "2021-01-08T00:00:00Z",
      "completed": false,
      "projectId": 7,
      "createdOn": "2021-01-08T12:50:45Z",
      "lastChangedOn": "2021-01-08T12:50:46Z",
      "creatorUserId": 1,
      "createdBy": 0,
      "reminder": false,
      "private": false,
      "status": "late",
      "userFollowingComments": false,
      "userFollowingChanges": false,
      "canEdit": true,
      "canComplete": true,
      "responsiblePartyIds": [
        1
      ],
      "commentsCount": 0
    }
  ],
  "meta": {
    "page": {
      "pageOffset": 0,
      "pageSize": 100,
      "count": 1,
      "hasMore": false
    }
  },
  "included": {
    "projects": {
      "7": {
        "id": 7,
        "name": "New Project",
        "description": "Test project",
        "type": "normal",
        "status": "active",
        "subStatus": "current",
        "companyId": 1,
        "tagIds": null,
        "startDate": null,
        "endDate": null,
        .....
      }
    }
  }
}

A GET request is sent with supported sparse fieldset query parameters to: http://YOURSITE/projects/api/v3/milestones.json?include=projects&fields[milestones]=id&fields[projects]=name

This returns a response of:

{
  "included": {
    "projects": {
      "7": {
        "name": "New Project"
      }
    }
  },
  "meta": {
    "page": {
      "pageOffset": 0,
      "pageSize": 100,
      "count": 1,
      "hasMore": false
    }
  },
  "milestones": [
    {
      "id": 1
    }
  ]
}

This reduces the number of fields in the response. If supported, any included objects can be filtered with sparse fieldsets.