hellomateo API Documentation

List endpoints return one page of objects at a time. Results are returned in reverse chronological order, with the newest objects first.

Pagination is controlled by the API. Use the next_page_url and previous_page_url values returned in the response to move through the result set, and treat page tokens as opaque values. Do not parse, edit, or construct page tokens yourself.

Start with the collection URL as-is. The API returns the first page with its default page size, and the response tells you how to continue.

List response shape

{
  "object": "list",
  "data": [],
  "next_page_url": "/v1/contacts?page_token=...",
  "previous_page_url": null
}

The data array contains the objects for the current page. If next_page_url is present, more results are available after this page. If it is null, you have reached the end of the list. previous_page_url can be used to move back toward newer results when it is present.

Request the first page

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

Example response:

{
  "object": "list",
  "data": [
    {
      "id": "018f2f82-4f7a-7a2f-9c4e-0123456789ab",
      "username": "mia.meyer",
      "full_name": "Mia Meyer",
      "email": "mia@example.com",
      "locale": "de",
      "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,
}

Request the next page

Use the returned next_page_url with the same API origin:

curl "https://api.getmateo.com/v1/employees?page_token=<opaque_page_token>" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 2026-07-01"

Example response:

{
  "object": "list",
  "data": [],
  "next_page_url": null,
  "previous_page_url": "/v1/employees?page_token=<opaque_previous_page_token>",
}

Prefer using the returned page URL directly. If your client needs to build the request URL itself, copy the returned page_token unchanged into the same endpoint with the same filters and includes. If you change filters, includes, or page size, a previously returned page token may no longer be valid for that request shape.

Optional query parameters

Most integrations do not need to pass pagination parameters on the first request.

Parameter	Type	Description
`page_token`	string	Opaque cursor returned by a previous page. Prefer using `next_page_url` or `previous_page_url` directly.
`limit`	integer	Optional page-size override. Defaults to `10`, maximum `100`. Omit unless your integration needs a custom size.

Some list endpoints also accept starting_after and ending_before. See Start from a known object.

Endpoint-specific list parameters are documented in the API reference. Query parameters that an endpoint does not document, including misspelled or renamed filters, return 400 instead of being ignored.

Start from a known object

Endpoints that document starting_after and ending_before in the API reference let you start a page at the ID of an object you already have, such as List Conversation Events.

Lists are sorted newest first, so:

Parameter	Returns
`ending_before=<id>`	Up to `limit` objects that are newer than `<id>`, starting closest to it
`starting_after=<id>`	Up to `limit` objects that are older than `<id>`, starting closest to it

The object itself is never included. Both parameters keep the newest-first order inside the page, and the returned next_page_url and previous_page_url continue from there.

starting_after, ending_before, and page_token are mutually exclusive. The ID must belong to an object that matches the request's filters; otherwise the API returns 400 with the code PAGINATION_ANCHOR_NOT_FOUND.

Poll for new objects

To fetch only objects you have not processed yet, pass the ID of the newest object you have processed as ending_before:

curl "https://api.getmateo.com/v1/conversation-events?ending_before=<newest_processed_event_id>&limit=100" \
  --header "Authorization: Bearer <your_api_token>" \
  --header "hellomateo-version: 2026-07-01"

Process data from last to first to handle objects oldest first, then store data[0].id as your new newest processed ID. Repeat the request with that ID until data is empty. Keep the same filters on every request.

Use this instead of created_at[gt]. Timestamps in responses are cut off at milliseconds, so a timestamp filter can return the object it came from again. See Timestamp precision.

Count badges

The public API does not return exact total counts for list endpoints. If your UI needs a badge count, request a bounded page such as limit=50 and treat next_page_url as the has-more signal: show 50+ when it is present. See Show Count Badges for examples.

Pagination