Include-dependent responses
Request endpoint-specific related data and details with include parameters.
All endpoints return compact resources by default. Additional related data or details must be requested explicitly with include[] query parameters.
Supported include values are endpoint-specific and documented in the API reference for each endpoint. Unsupported include values return a JSON error response.
Include syntax
Use repeated include[]=value query parameters for standard includes:
include[]=teams&include[]=another_supported_valueExample
Employee list responses include employee objects by default. The same request returns a compact employee unless you ask for additional related data.
Without include
curl "https://api.getmateo.com/v1/employees" \
--header "Authorization: Bearer <your_api_token>" \
--header "hellomateo-version: 2026-07-01"The response uses the standard list envelope. The employee object does not include teams:
{
"object": "list",
"data": [
{
"id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
"display_name": "Mia Meyer",
"username": "mia.meyer",
"full_name": "Mia Meyer",
"email": "mia@example.com",
"user_id": "018f2f82-4f7a-7a2f-9c4e-1123456789ab",
"is_admin": false,
"signature": null,
"organisation_id": "018f2f82-4f7a-7a2f-9c4e-2123456789ab",
"locale": "de",
"enable_shortcuts": true,
"is_web_push_enabled": false,
"is_mobile_push_enabled": false,
"has_mobile_device": false,
"is_active": true,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
},
],
"next_page_url": "/v1/employees?page_token=<opaque_page_token>",
"previous_page_url": null,
}With include
Add include[]=teams to request the teams for each employee:
curl "https://api.getmateo.com/v1/employees?include[]=teams" \
--header "Authorization: Bearer <your_api_token>" \
--header "hellomateo-version: 2026-07-01"The response envelope is the same, but each employee object now includes teams:
{
"object": "list",
"data": [
{
"id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
"display_name": "Mia Meyer",
"username": "mia.meyer",
"full_name": "Mia Meyer",
"email": "mia@example.com",
"user_id": "018f2f82-4f7a-7a2f-9c4e-1123456789ab",
"is_admin": false,
"signature": null,
"organisation_id": "018f2f82-4f7a-7a2f-9c4e-2123456789ab",
"locale": "de",
"enable_shortcuts": true,
"is_web_push_enabled": false,
"is_mobile_push_enabled": false,
"has_mobile_device": false,
"is_active": true,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z",
"teams": [
{
"id": "018f2f82-4f7a-7a2f-9c4e-3123456789ab",
"name": "Sales",
"emoji": "👥",
},
],
},
],
"next_page_url": "/v1/employees?include%5B%5D=teams&page_token=<opaque_page_token>",
"previous_page_url": null,
}Endpoint-specific behavior
Includes are not portable across endpoints. Check the API reference for the exact endpoint you are calling before relying on a relationship or detail field.
include[] controls the response shape only. To update supported relationships, see Updating relationships.