Filtering API results

When fetching a list of results it is common to filter down the data set based on some business criteria. For example, instead of listing all customers you may want to show only customers within a single company. Some APIs implement this filter as a sub-route. In general the Desk API implements this filtering ability not based on sub-routes but by use of the filter query parameter (also accepted via body parameter in a POST).

As often as possible we will make most fields (especially relationships) filterable, but there are cases where we simply cannot support filtering on certain fields (contains on body on threads for example). In these cases we usually have a search API endpoint to be used for full-text lookups.

Syntax

The following operators are supported

const (
Eq Operator = "$eq"
Ne Operator = "$ne"
Lt Operator = "$lt"
Lte Operator = "$lte"
Gt Operator = "$gt"
Gte Operator = "$gte"
In Operator = "$in"
Nin Operator = "$nin"
And Operator = "$and"
Or Operator = "$or"
Contains Operator = "$contains"
)

Filter Operators

Supported operators

$eq =
$ne !=
$lt <
$lte <=
$gt >
$gte >=
$in { qty: { $in: [ 5, 15 ] } }
$nin !$in
$and { $and: [ { price: 1.99 }, { qty: { $lt: 20 } }, { sale: true } ] }
implicit $and { price: 1.99, qty: { $lt: 20 } , sale: true }
$or { price:1.99, $or: [ { qty: { $lt: 20 } }, { sale: true } ] }

Not supported

$all, $nor, $not, etc

Filter examples

Examples

?filter={}
?filter={"age": 20}
?filter={"age": 20, "name": "mike"}
?filter={"age": {"$eq": 20}}
?filter={"age": {"$ne": 20}}
?filter={"age": {"$lt": 20}}
?filter={"age": {"$gt": 20}}
?filter={"age": {"$lte": 20}}
?filter={"age": {"$gte": 20}}
?filter={"age": {"$in": [20, 1]}}
?filter={"age": {"$nin": [20, 1]}}
?filter={"$or": [{"age":{"$gt": 20}}, {"name": "mike"}]}
?filter={"$or": [{"age":{"$gt": 20}}, {"name": "mike"}, {"$and": [{"age": {"$gt": 12}}, {"age": {"$lte": 18}} ]}]}
?filter={"$or": []}

Filter examples based on specific endpoints

Get Users

Endpoint doc: https://apidocs.teamwork.com/docs/desk/v2/users/get-v2-users-json

Include archived users:

?includeArchived=true

Archived users only:

?includeArchived=true&filter={"state":{"$eq": "archived"}}

Get paginated list of tickets

Endpoint doc: https://apidocs.teamwork.com/docs/desk/v2/tickets/get-v2-tickets-json

Return all tickets of any state:

Operators: 'in'

?filter={"state":{"$in":["active","scheduled","merged","deleted"]}}

Return all tickets created between date range and specified inboxes:

Operators: 'and', 'gt', 'lt', 'in'

?filter={"$and":[{"createdAt":{"$gt":"2024-07-01T00:00:00.000Z"}},{"createdAt":{"$lt":"2024-08-01T00:00:00.000Z"}},{"inboxes.id":{"$in":[ 1262, 1564, 2346, 2370]}}]}

Return all tickets updated after a specified date:

Operators: 'gt' - date format yyyy-mm-dd

?filter={"updatedAt": {"$gt": "2024-08-05"}}

To narrow down your payload to deleted tickets based on your deletedAt date:

Operators: 'and', 'in', 'gt'

?filter={"$and":[{"state":{"$in":["deleted"]}},{"deletedAt": {"$gt": "2024-07-17T18:59:47Z"}}]}

Get customers

Endpoint doc: https://apidocs.teamwork.com/docs/desk/v2/tickets/get-v2-tickets-json

Welcome email sent to customer:

Operators: 'eq'

?filter={"welcomeEmailSent":{"$eq": true}}

Address contains a value:

Operators: 'contains'

?filter={"address":{"$contains": "Ireland"}}

Customer updated on or after specified date

Operators: 'gte'

?filter={"updatedAt":{"$gte": "2024-04-01"}}