Includes allow you to return additional resources with your requests.
Often times, you will want to retrieve additional data when making an API call rather than having to make subsequent calls to get all of the data you need. For these scenarios, you can use an include query parameter in your GET requests.
Syntax
To utilize includes correctly, the include parameter must be included as a query parameter in your requests. A request can only have a single include query parameter but this parameter can have multiple values separated by a comma if needed:
?include=company?include=company,account,lead
Include example
Take for example Projects. Say you wanted to get all data for a Project with an id of 42 as well as the Account, Lead and Workflow the Project belongs to. Normally, you would have to make four separate API calls to get all the data you need:
GET /api/projects/42
GET /api/accounts/{account_id}
GET /api/companies/{company_id}/leads/{lead_id}
GET /api/companies/{company_id}/workflows/{workflow_id}
Additionally, you would also have to parse out the {account_id}, {company_id}, {lead_id} and {workflow_id} values from your initial call within the returned Project payload in order to make your subsequent calls.
Instead, you can instruct the API to return the Project's Account, Lead and Workflow along with the Project data in one call:
GET /api/projects/42?include=account,lead,workflow
As you can see, you can include multiple relations by separating them with a comma. Each entity / resource has a corresponding type documentation with an "Allowed includes" section.