Pagination & Sorting (Search)

When you use any Search resource, we require you to make a POST request that will not accept the common query params of GET requests. Therefore, the structure here has slight variations to our cursor-based approach.

📘

This currently only applies to Searching for Contacts and Searching for Conversations.

Pagination

{
 "query":  {
    "field": "name",
    "operator": "=",
    "value": "alex"
  },
  "pagination": {
    "per_page": 5,
  } 
}

You can specify how many items per page you want to fetch.

📘

Default pagination amount

If pagination is not provided, the request defaults to 50 items.

{
  "pages": {
  "type": "pages",
  "next": {
    "page": 4,
    "starting_after": "1HaSB+xrOyyMXAkS/c1RteCL7BzOzTvYjmjakgTergIH31eoe2v4/sbLsJWP\nIncfQLD3ouPkZlCwJ86F\n"
  },
  "page": 3,
  "per_page": 5,
  "total_pages": 10
  }
}

In order to iterate through pages, you must parse the query response. A query with multiple response pages will include a next key in the pages hash. When a next value is provided, the starting_after value must be sent back in a new request to iterate to the next page.

🚧

Paginating through all results

This method of pagination is used to iterate through a result set until all results have been fetched, not to directly go to page X of the results. This is not possible.

{
 "query":  {
    "field": "name",
    "operator": "=",
    "value": "alex"
  },
  "pagination": {
    "per_page": 5,
    "starting_after": "1HaSB+xrOyyMXAkS/c1RteCL7BzOzTvYjmjakgTergIH31eoe2v4/sbLsJWP\nIncfQLD3ouPkZlCwJ86F\n"
  } 
}

🚧

Warning about search context state

The starting_after context is stateless. Consequently, if items are updated between 2 paginated queries, this can lead to duplicate or missed records.

For example, if a query is sorting results by number of sessions and an item is updated from 1 session to 2 sessions during the pagination, they may be listed on page 1 of the results, but also on page 2.

Sorting

{
 "query":  {
    "field": "name",
    "operator": "=",
    "value": "alex"
  },
  "sort": {
    "field": "name",
    "order": "ascending"
  } 
}

The Search resources can also sort query results by using the following parameters within the sort object:

📘

Default sort order

If no sort pattern is provided, the query will use the default sorting parameter "last_request_at" with a descending value (e.g. listing most recent active items first).