The fields query parameter

Every endpoint returns a default set of fields. You can override this default set using the fields query parameter. This is useful when you need properties not returned by default, or when you want to avoid getting properties that are not necessary.

You can also use the fields query parameter for related resources added through the include parameter. For more information, see Query parameters for included resources.

The fields parameter can be set to one or more of the following values:

  • *all - Return all fields
    Note: *all is not recommended for production environments. For more information, see the following section on "Returning all fields".
  • *default - Return the default fields (typically used in conjunction with an additional field list)
  • fieldList - Return one or more fields specified as a comma-delimited list

The "detail list" and "summary list" of fields

For endpoints that return a single element, the default fields to return are defined in a detail list. Similarly, for endpoints that return a collection, the default fields to return are defined in a summary list.

For example, the following list compares the detail list fields for a contact resource (for example, the default fields for the /accounts/{accountId}/contacts/{contactId} endpoint) and the summary list fields returned for a contact collection (for example, the default fields for the /accounts/{accountId}/contacts endpoint). Fields included in the detail list only are in bold:

  • Detail list: companyName, contactSubtype, displayName, emailAddress1, emailAddress2, id, industryCode, primaryPhoneType, subtype, taxId
  • Summary list: companyName, contactSubtype, displayName, emailAddress1, id, industryCode, subtype, taxId

The fields parameter has three options related to these default sets:

  • *detail - Return the fields in the "detail list"
  • *summary - Return the fields in the "summary list"
  • *default - Return the default list. If the endpoint returns a single element, the default is the "detail list". If the endpoint returns a collection, the default is the "summary list"

Returning the default properties plus additional specific properties

Some API calls need a set of fields that is not exactly equivalent to either the detail list or the summary list. These calls can name specific fields, either on their own or in addition to a default list of fields. They can also specify all fields.

To return the default fields of an endpoint with an additional set of fields, use:

fields=*default,fieldList

where fieldList is a comma-delimited list of fields.

For example, the following query returns all default fields for activity xc:20 as well as the description and the start date.

GET /activities/xc:20?fields=*default,description,startDate

Returning a specific set of properties

To return a specific set of fields, use:

fields=fieldList

where fieldList is a comma-delimited list of fields.

For example, the following query returns only the description and the start date for activity xc:20:

GET /activities/xc:20?fields=description,startDate

Returning a specific set of properties on inlined resources

Some response payloads include inlined resources in the attributes section. For example, the following is a portion of the response for a GET /activities. This payload contains two inline resources, assignedGroup and assignedUser.

"attributes": {
    "activityPattern": "contact_claimant",
    "assignedGroup": {
        "displayName": "Auto1 - TeamA",
        "id": "demo_sample:31"
    },
    "assignedUser": {
        "displayName": "Andy Applegate",
        "id": "demo_sample:1"
    },
    "closeDate": "2020-04-06T07:00:00.000Z",
    "dueDate": "2020-04-06T07:00:00.000Z",
    "escalated": false,
    "id": "cc:20",
    ...
}

You can use the fields query parameter to specify an inlined resource. When you do, all default fields for that resource are returned. For example, you could specify that you want a GET /activities to return only the assignedGroup and assignedUser fields (and all of their default subfields) using the following:

GET /activities?fields=assignedGroup,assignedUser

This would return:

"attributes": {
    "assignedGroup": {
        "displayName": "Auto1 - TeamA",
        "id": "demo_sample:31"
    },
    "assignedUser": {
        "displayName": "Andy Applegate",
        "id": "demo_sample:1"
        }
}

You can also specify specific subfields using the following syntax:

fields=inlinedResourceName.fieldName

For example, you could specify that you want a GET /activities to return only the ids of the assigned user and group using the following:

GET /activities?fields=assignedGroup.id,assignedUser.id

This would return:

"attributes": {
    "assignedGroup": {
        "id": "demo_sample:31"
    },
    "assignedUser": {
        "id": "demo_sample:1"
        }
}

Returning all fields

To return all of the fields that an endpoint is configured to return, use:

fields=*all

For example, the following query returns all the possible fields for activity xc:20.

GET /activities/xc:20?fields=*all

Note that the *all query parameter returns all fields that the caller is authorized to view. If there are fields on a resource that a caller is not authorized to view, they are excluded from queries using the *all query parameter.

*all is not recommended for production environments as it may return fields that are not included in default responses because they require additional resources to calculate. Instead, use the *default filter with any specific fields that do not appear in the default detail or summary list.

The fields query parameter with POSTs and PATCHes

You can also use the fields query parameter with POSTs and PATCHes to control which fields are returned in the response. For example, the following request creates a new user. The response will contain the default fields for a User resource (such as active, id, username, and vacationStatus).

POST /admin/v1/users

The following request also creates a new user. But, the response will contain only the id.

POST /admin/v1/users?fields=id
The fields query parameter is the only parameter you can use with POSTs and PATCHes.

Specifying fields for included resources

For information on how to use the fields parameter with included resources, see Query parameters for included resources.

Tutorial: Send a GET with the fields parameter

This tutorial assumes you have set up your environment with Postman and the correct sample data set. For more information, see Tutorial: Set up your Postman environment.

Tutorial steps

  1. In Postman, start a new request by clicking the + to the right of the Launchpad tab.
    1. On the Authorization tab, select Basic Auth using user aapplegate and password gw.
  2. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities

  3. Open a second request tab and right-clicking the first tab and selecting Duplicate Tab.
  4. Enter the following and click Send:

    GET http://localhost:8180/pc/rest/common/v1/activities?fields=id,subject

Checking your work

Compare the two payloads. Note that the first response payload includes the default fields for activities, whereas the second response payload includes only the two fields specified in the fields query parameter.