Release Candidate — the API is undergoing final validation before general availability, and minor changes may still occur.
Hellomateo API Documentation
DocumentationAPI Reference
Working with the API

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[]=statuses&include[]=another_supported_value

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%5B%5D=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.

Pagination

Work with cursor-based list responses.

Updating relationships

Update supported relationships together with a resource.

On this page

Include syntax
Example
Without include
With include
Computed references
Endpoint-specific behavior