Querying the API

Helpdocs Admin Updated by Helpdocs Admin

Most collection endpoints in v4 support filtering, searching, and ordering through a single POST request. Rather than a dedicated query language, you send a JSON payload describing what you want — including pagination, text search, property filters, and sort order.

Use skip and take to page through results:

{
  "skip": 0,
  "take": 25
}

Full text search

To search across an entity's text fields, use the term property (older endpoints may still use search — term is now preferred):

{
  "term": "printer offline"
}

Any text you provide is tokenized by splitting on spaces, then matched using full text search. Exact matches are weighted more heavily than prefix matches.

Note: Because tokenization is space-based, this works best for English and other space-separated languages. It isn't currently optimized for languages that don't use spaces between words. We're exploring vector search for some collections in the future, which would remove this limitation.

Filtering by property

List-based filters (v2/v3 style)

Older versions let you filter a property by providing a list of IDs. The server matches entities where the property contains any of the listed values:

{
  "queues": [{ "entityId": 33, "name": "support" }],
  "assignees": [{ "entityId": 234, "name": "agent" }]
}

A few things to know:

  • The server only reads entityId — name is included for UI display purposes only and can be left blank or null.
  • Within a single property, multiple values are combined with OR (match any).
  • Between different properties, the filter is combined with AND.

The example above returns entities in either queue 33 and assigned to agent 234 — i.e., must match both the queue condition and the assignee condition.

Operator-based filters (v4)

v4 introduces an operator for each property, giving you more control than a simple "contains any" match:

{
  "queues": { "operator": "in", "value": [{ "entityId": 33, "name": "support" }] },
  "assignees": { "operator": "exist" }
}

This example returns entities in queue 33 that also have any assignee. As before, conditions across different properties are combined with AND — only the logic within a single property has more options now.

Operator types

There are two operator variants, depending on whether the property is a single value or a collection:

export type TokenOperator =
  | 'in'
  | 'not_in'
  | 'exist'
  | 'not_exist';

export type TokenCollectionOperator =
  | 'all_in'
  | 'not_all_in'
  | 'in'
  | 'not_in'
  | 'exist'
  | 'not_exist';

Use TokenCollectionOperator for properties that are themselves collections on the entity — it adds all_in / not_all_in, letting you match entities that contain all specified values, not just any of them.

Simple filters

Some filters don't need an operator at all — for example, filtering by entity state or a boolean property. These accept the value directly.

Filtering by metadata

Several entities — including agent, contact, account, ticket, comment, and time entry — support metadata: custom string-to-string key/value pairs you define. Metadata is a useful place to store references to external systems, such as mapping an account to a company record in another platform (e.g., a zendesk_organization_id key holding that system's ID as the value).

Metadata filtering always uses TokenOperator (in, not_in, exist, not_exist) — full text search isn't available on metadata fields, but these four operators cover most scenarios.

Provide metadata filters as a list, since you can filter on multiple keys at once:

{
  "metadata": [
    { "key": "organization_id", "operator": "in", "value": ["1", "3"] }
  ]
}

Ordering results

Where supported, use the order property to sort results. You can provide multiple fields, applied in sequence:

{
  "order": ["-name", "created_at"]
}

This example sorts by name descending first, then by created_at ascending for any ties. All order tokens sort ascending by default — prefix a token with - to sort descending.

Each entity has its own set of supported order tokens. For example, tickets support:

export type TicketOrderToken =
  | 'name'
  | 'id'
  | 'last_modified_at'
  | 'last_comment_at'
  | 'created_at'
  | 'relevance';
Tip: When performing a full text search (using term), it's best to leave order unset, or explicitly use relevance. Full text search has its own internal weighting system for ranking results, which a manual sort order would override.

Finding the exact filters available for an entity

Every entity has its own specific set of filterable properties and order tokens. To see the full definition for a given endpoint, use our TypeScript conversion tool:

/swagger/index.html?urls.primaryName=Internal+API+V2#/TypeScript/get_api_v2_typescript_api

Provide a root-level path (e.g., /api/v4/accounts) to generate a TypeScript definition showing exactly which properties, operators, and string enums are supported for that entity.

How did we do?

Authorization Options

How to Change an Entity Through the API

Contact