Filter tasks using Custom Fields

Use Custom Fields to filter tasks via the following endpoints:

• Get Tasks: For tasks within a specific List.
• Get Filtered Team Tasks: For tasks across your entire Workspace.

👍

Tip

Use Get Tasks when you know the List where the tasks are located. Use Get Filtered Team Tasks to find tasks anywhere in your Workspace.

Using Custom Field Filters

When filtering by a Custom Field, provide a stringified JSON array of objects that must include the following properties:

• field_id
• value
• operator

field_id

The field_id refers to the ID of the Custom Field you want to filter by. Retrieve it using the Get Accessible Custom Fields endpoint.

Operators

The supported operators for filtering are:

• =- contains (fuzzy match)
• ==- exact match for text Custom Fields
• < - less than
• <= - less than or equal to
• > - greater than
• >= - greater than or equal to
• != - not equal to
• != - does not contain for text Custom Fields.
• !==- does not exact match for text Custom Fields.
• IS NULL - field is not set
• IS NOT NULL - field is set
• RANGE - is between
• ANY - matches any criteria
• ALL - matches all criteria
• NOT ANY - does not match any criteria
• NOT ALL - does not match all criteria

Value

The value corresponds to the data in the Custom Field. This depends on the Custom Field type.

👍

Tip

Create a task and add a value to the Custom Field you want to filter. Then, use the Get Task endpoint to identify the field_id and its acceptable value.

Example Query

Here's an example of a Custom Field query parameter:

?custom_fields=[{"field_id":"de761538-8ae0-42e8-91d9-f1a0cdfbd8b5","operator":">","value":2},{...}]

Breakdown

1. field_id: Identifies the Custom Field. In this case, it's a Number Custom Field named Number of Reports.
2. operator: Specifies the comparison operator. Here, > means "greater than."
3. value: Specifies the threshold value. In this example, it's 2.

This query returns tasks where the Number of Reports is 3 or more.

4. {...}: Represents additional Custom Fields to include in the filter, if needed.

Example Query

Here's another example of a Custom Field query parameter:

?custom_fields=[{"field_id":"ac123456-8ae0-42e8-91d9-f1a0cdfb1ce7","operator":"=","value":"project"},{...}]

Breakdown

In this example we're looking for tasks that contains the word project.

1. field_id: Identifies the Custom Field. In this case, it's a Short text Custom Field named Feature.
2. operator: Specifies the comparison operator. Here, = means "contains".
3. value: Specifies the text in the field. In this example, it's project.
4. {...}: Represents additional Custom Fields to include in the filter, if needed.

Find exact matches

To find exact matches, we can use the same query with the ==operator instead:

?custom_fields=[{"field_id":"ac123456-8ae0-42e8-91d9-f1a0cdfb1ce7","operator":"=","value":"project"},{...}]

Breakdown

field_id: Identifies the Custom Field. In this case, it's a Short text Custom Field named Feature.

1. operator: Specifies the comparison operator. Here, == means "exact match".
2. value: Specifies the exact text in the field. In this example, it's project.
3. {...}: Represents additional Custom Fields to include in the filter, if needed.