Filtering, Sorting and Pagination

Get many requests such as the List all cases operation have filtering, sorting and pagination mechanisms. Here is an overview of how these various systems work.

Filtering items

The filtering system allows you to exclude some items from responses served by the API.

The API documentation states which fields and operators can be used for filtering for each endpoint.

If more than one filter is specified, the filters are combined using AND logic, which means that all values will match the specified filters.

Filtering operators reference

eq

default operator if none is specified

Narrow the response data set to items’ field that match the given value.

Examples:

  • /cases?name.eq=john
  • /webhooks?type.eq=user

not_eq

Narrow the response data set to items’ field that does not match the given value.

Example:

  • /cases?status.not_eq=open
  • /webhooks?type.not_eq=zapier

lt, lte, gt, gte

Narrow the response data set to items’ field which value is either…

  • less-than (lt)
  • less-than-or-equal (lte)
  • greater-than (gt)
  • greater-than-or-equal (gte)

… to the given value.

This operator can work for number and date-time fields. If data type is date-time, value must be formatted as an ISO8601 date and time object.

Example:

  • /cases?updated_at.lt=2022-01-27T00:00:00Z

like, ilike

Narrow the response data set to items’ field which value match the given pattern.

The like operator is case sensitive, while the ilike operator is case insensitive.

Pattern format:

  • The _ character match any character exactly 1 time. It’s the equivalent of the {1} ReGex
  • The % character match any character sequence. It

Example:

  • /cases?name.ilike=%doe
    This would match any cases which as a name ending with doe.

in, not_in

Narrow the response data set to items’ field which value are respectively in and not in the given list.

Pattern format:

  • value should be a comma-separated list

Example:

  • /cases?status.in=open
    This would match any cases with a status open. This is equivalent to the eq operator.
  • /cases?status.not_in=open
    This would match any cases with a status not open. This is equivalent to the not_eq operator.
  • /cases?status.in=open,approved
    This would match any cases with a status either open or approved.
  • /cases?status.in=rejected,approved
    This would match any cases with a status neither rejected nor approved

array_contains, array_not_contains, array_overlap

Only for array types (e.g: Case.tags)

Narrow the response data set to item’s field which value are respectively including all elements, including no element and including at least one element in the given list.

Pattern format:

  • value should be a comma-separated list

Example:

  • /cases?tags.array_contains=High risk,Low risk
    This would match any cases with tags including both High risk and Low risk.
  • /cases?tags.array_not_contains=High risk,Low risk
    This would match any cases with tags including neither High risk nor Low risk.
  • /cases?tags.array_overlap=High risk,Low risk
    This would match any cases with tags including either High risk or Low risk.

🚧

Comma-separated list elements should be trimmed

/cases?status.in=open,approved use open and approved as values.
/cases?status.in=open, approved will produce a validation error as approved ≠ approved (leading space is not rendered)

Sorting items

The sorting system gives control on the order on which items are returned by the API.

The API documentation states which fields and operators can be used for filtering for each endpoint.

Sorting options are specified via the sort query parameter:

  • the default sorting order is ascending. It can be overridden with a .asc or .desc suffix.
  • multisort is by separating the fields with commas (,).

Examples:

  • /case?sort=status,updated_at.desc
  • /webhooks?sort=created_at

Pagination

Paginated queries accepts two query parameters limit and page.

Examples:

  • /cases?page=23&limit=50
  • /webhooks?page=42

Response metadata

Paginated queries return a pagination metadata object alongside the returned items. This object specifies the current page, the items per page (limit) and the total items count.

{
  "data": [...],
  "pagination": {
    "page": 1,
    "limit": 20,
    "count": 175
  }
}