`include`

To limit the response body to specific properties, use the include query string parameter.

The value for the include query string parameter is a list of properties separated by bars (|). You must URL encode the bars as %7C. Include a forward slash before every property name.

The following request includes only the aboutMe property and the address property in a response body:

1/chatter/users/me?include=/aboutMe%7C/address

The following rules describe how to use the include query parameter.

Forward Slashes

Include a forward slash (/) before property names or the request returns an error.

Original output:

1{
2  "bar": "bar value",
3  "baz": "baz value"
4}

Include value: include=bar

Filtered output: 400 error with error code INVALID_FILTER_VALUE.

Filter properties by name.

Original output:

1{
2  "bar": "bar value",
3  "baz": "baz value"
4}

Include value: include=/bar

Filtered output:

1{
2  "bar": "bar value"
3}

Ignore Top-Level Properties

Top-level properties are ignored. Note there is no error when you try this.

Original output:

1<foo>
2  <bar>bar value</bar>
3  <baz>baz value</baz>
4</foo>

Include value: include=/foo

Filtered output:

1<foo>
2  <bar>bar value</bar>
3  <baz>baz value</baz>
4</foo>

Multiple Properties

Use a bar (|) delimiter to filter multiple properties. URL encode the delimiter as %7C.

Original output:

1{
2  "foo": "foo value",
3  "bar": "bar value",
4  "baz": "baz value"
5}

Include value: include=/foo%7C/bar

Filtered output:

1{
2  "foo": "foo value",
3  "bar": "bar value"
4}

Filtering a response body filters everything below it.

Original output:

1<foo>
2  <bar>bar value</bar>
3  <baz>baz value</baz>
4  <someObject>
5    <sub>sub 1</sub>
6  </someObject>
7</foo>

Include value: include=/someObject

Filtered output:

1<foo>
2  <someObject>
3    <sub>sub 1</sub>
4  </someObject>
5</foo>

Nested Properties

To filter a property nested in a response body, include the parent response body name as a filter segment.

Original output:

1<foo>
2  <bar>bar value</bar>
3  <baz>baz value</baz>
4  <someObject>
5    <sub>sub value</sub>
6  </someObject>
7</foo>

Include value: include=/someObject/sub

Filtered output:

1<foo>
2  <someObject>
3    <sub>sub value</sub>
4  </someObject>
5</foo>

XML List Items

Identify an item in a list by its property name. This example uses XML.

Original output:

1<foo>
2  <bar>bar value</bar>
3  <baz>baz value</baz>
4  <someList>
5    <item>
6      <id>1</id>
7    </item>
8    <item>
9      <id>2</id>
10    </item>
11    <item>
12      <id>3</id>
13    </item>
14  </someList>
15</foo>

Include value: include=/someList/item/id

Filtered output:

1<foo>
2  <someList>
3    <item>
4      <id>1</id>
5    </item>
6    <item>
7      <id>2</id>
8    </item>
9    <item>
10      <id>3</id>
11    </item>
12  </someList>
13</foo>

JSON List Items

Identify an item in a list by its property name. This example uses JSON.

Original output:

1{
2  "bar": "bar value",
3  "baz": "baz value",
4  "someList": [
5    {
6      "id": "1"
7    },
8    {
9      "id": "2"
10    },
11    {
12      "id": "3"
13    }
14  ]
15}

Include value: include=/someList/item/id

Filtered output:

1{
2  "someList": [
3    {
4      "id": "1"
5    },
6    {
7      "id": "2"
8    },
9    {
10      "id": "3"
11    }
12  ]
13}