Expand

When you get an Detailed respresentation of an resource, the default response does not include related resource. For example, here is the response for the Agreement Details endpoint:

Example: GET /agreement/bb1aadf3-8aee-494b-a6f5-5f8dd15357f0

curl -k -i -H "Content-Type: application/json"\ 
-H "X-Token: {api-token}"\ 
-X GET 'https://{host-name}/agreements/{agreementID}'

When you get an individual agreement, you get the detailed representation of the agreement.

Sample Response

As you can see, the response does not include any clauses, versions, attributes and all are returned as null. However, the client can use expand to get the related resources for this agreement.

The expand option goes in the query string of the request:

Not all attributes support expand, attributes supporting expand will be marked as such in model definition in this documentation.

Example GET /agreement/123?expand=attributes

Now the server will include the attributes in detail representation :

The expand option takes a comma-separated list of navigation properties to expand. The following request expands both the attributes and the versions for a agreement.

GET /agreement/123?expand=attributes,versions

Expansion Depth

By default, API limits the expansion depth to 2. That prevents the client from sending complex requests like expand=clauses(expand=standardclause(expand=details)) which might be inefficient to query and create large responses.

Partial response in Expand

To return the partial response in expandable attributes; please specify select query paramater for expandable resources.

For Example

GET /agreement/123?select=id, clauses,versions & expand=clauses(select=id,name),versions(select=id,name)

In the above example response will include id from agreement; id and name from clauses ; id and name from versions.

Filtering in Expand

To filter the response in expandable attribute; please specify filter query paramater.

For Example

GET /agreement/123?expand=clauses(filter = name $eq 'Payment Terms'), versions(filter=uploadedBy $eq 'CLM ADMIN')

In the above example response of clauses will be filtered by filter expression (name $eq 'Payment Terms') and response of versions will be filtered by filter expression (uploadedBy $eq 'CLM ADMIN').

Refer Filtering section to know more about on how to build filter expressions.

Sorting in Expand

To sort the response in expandable attribute; please specify sort query paramater. Comma seperated sort expressions is supported for multiple expandable attributes.

For Example

GET /agreement/123?expand=clauses(sort = name asc) ,versions(sort=uploadedBy desc)

In the above example response of clauses will be sorted by sort expression (name asc) and response of versions will be sorted by sorted expression (uploadedBy desc)

Refer Sorting section to know more about on how to build sort expressions.

Pagination in expand

When you expand the resource which returns the list it will always be limit to the default page size for that resource. Default page size will be mentioned on the resource endpoints in this documentation.

If you want the expanded resources to honor the pageSize please send pageSize paramater in expand resource.

For Example

GET /agreement/123?expand=clauses(pageSize=10) ,versions(pageSize=5)

In the above example response of clauses will be limited to 10 records and response of versions will be limited to 5 records

Refer Pagination section to know more.

Combining multiple expression

Many times we would like to get response of expanded resources which are filtered, sorted and respects the pageSize as well.

You can do this by passing all the supported request parameters in expand expression.

For example -

If we want to expand versions in agreement that should be filtered by uploadedBy property and also want to sort the response by version and only get 5 records . you can do this by forming the below query.

GET /agreement/123?expand= versions(filter = uploadedBy $eq 'CLM ADMIN' | sort = version desc | pageSize=5 | select = id,name,uploadedBy)

The pipe character is used to separate the request parameters query inside expand.