Include-dependent responses

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 400 with a JSON error response.

Include syntax

Use repeated include=value query parameters for standard includes:

include=statuses&include=another_supported_value

The bracket form include[]=value is not supported and returns 400, like any other query parameter that the endpoint does not document.

Contacts, deals, and appointments use repeated include_details parameters for custom detail fields. List, ID, and locator reads support the same syntax:

GET /v1/contacts/by?external_id=customer-123&include_details=plan_type&include_details=region

Example

Deal type list responses contain deal type objects by default. Statuses are only present when requested.

Without include

curl "https://api.getmateo.com/v1/deal-types" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 2026-07-01"

The response uses the standard list envelope. The deal type object does not include statuses:

{
  "object": "list",
  "data": [
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
      "key": "sales",
      "name": "Sales",
      "emoji": "🤝",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
    },
  ],
  "next_page_url": "/v1/deal-types?page_token=<opaque_page_token>",
  "previous_page_url": null,
}

With include

Add include=statuses to request the statuses for each deal type:

curl "https://api.getmateo.com/v1/deal-types?include=statuses" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 2026-07-01"

The response envelope is the same, but each deal type object now includes statuses:

{
  "object": "list",
  "data": [
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
      "key": "sales",
      "name": "Sales",
      "emoji": "🤝",
      "created_at": "2026-01-01T00:00:00.000Z",
      "updated_at": "2026-01-01T00:00:00.000Z",
      "statuses": [
        {
          "id": "018f2f82-4f7a-7a2f-9c4e-1123456789ab",
          "key": "open",
          "name": "Open",
          "type": "open",
          "idx": 0,
        },
      ],
    },
  ],
  "next_page_url": "/v1/deal-types?include=statuses&page_token=<opaque_page_token>",
  "previous_page_url": null,
}

Computed references

Computed references follow the same include rules as relationships. Conversations expose assignee only with include=assignee, and messages expose author only with include=author. The property is absent without the include and is null when requested but no reference exists.

A message retrieve can request its conversation and the conversation assignee together:

include=conversation&include=conversation.assignee

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.