List, filter, and sort
Use page, pageSize, where, and order on the list endpoints.
Most list endpoints (GET /v1/conversations, GET /v1/projects, GET /v1/contacts, GET /v1/tags, GET /v1/webhooks, and more) take the same four query parameters:
| Parameter | What it does | Default |
|---|---|---|
page | The page number, from 1. | 1 |
pageSize | The number of records on each page, from 1 to 100. | 10 |
where | A filter, as JSON. | No filter |
order | The sort order, as JSON. | Newest first |
Pages
To get all records, increase page by 1 until a page has fewer records than pageSize.
GET /v1/conversations?page=2&pageSize=100GET /v1/spark-templates is different: it uses limit and cursor. Send the nextCursor from each response as cursor in the next request. The last page has nextCursor: null.
Filter with where
wherewhere is a JSON object. Each key is a field name from the API response. Each value is an operator and a value:
{ "status": { "$eq": "ReadyForReview" } }If you put more than one field in the object, a record must match all of them:
{
"status": { "$eq": "ReadyForReview" },
"createdAt": { "$gte": "2026-10-01" }
}| Operator | Matches | Example |
|---|---|---|
$eq | Equal to | { "status": { "$eq": "Completed" } } |
$ne | Not equal to | { "status": { "$ne": "Completed" } } |
$gt, $gte | Greater than, greater than or equal to | { "createdAt": { "$gte": "2026-10-01" } } |
$lt, $lte | Less than, less than or equal to | { "createdAt": { "$lt": "2026-01-01" } } |
$in | One of the values in a list | { "status": { "$in": ["InProgress", "Completed"] } } |
$like | A text pattern, case-sensitive. % matches any text. | { "name": { "$like": "Smith%" } } |
$ilike | A text pattern, not case-sensitive | { "name": { "$ilike": "%kitchen%" } } |
$is | null | { "projectId": { "$is": null } } |
$not | Not equal to one value | { "status": { "$not": "Completed" } } |
$not takes one value. It does not take another operator, so { "$not": { "$in": [...] } } returns 400.
Sort with order
orderorder is a JSON list of [field, direction] pairs. The direction is ASC or DESC.
[["status", "ASC"], ["createdAt", "DESC"]]Example
This JavaScript example gets the newest 25 Conversations that are ready for review:
const where = JSON.stringify({ status: { $eq: "ReadyForReview" } });
const order = JSON.stringify([["createdAt", "DESC"]]);
const url = new URL("https://public-api.production.liveswitch.com/v1/conversations");
url.searchParams.set("page", "1");
url.searchParams.set("pageSize", "25");
url.searchParams.set("where", where);
url.searchParams.set("order", order);
const response = await fetch(url, {
headers: { Authorization: `Bearer ${accessToken}` },
});
const conversations = await response.json();URLSearchParams encodes the JSON for you. If you build the URL yourself, encode where and order with encodeURIComponent.
Errors
| Error | Cause |
|---|---|
400 Invalid where clause — "where" must be valid JSON. | where is not valid JSON. |
400 Invalid where column "…". | The field name does not exist. |
400 Invalid sort column "…". | The field in order does not exist. |
400 The field PageSize must be between 1 and 100. | pageSize is less than 1 or more than 100. |
Updated 1 day ago