The fields query parameter

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

Specifying fields for included resources

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