Filtering Lists

To filter a list endpoint, append the “filter” query string parameter and specify the property you want to filter on. Multiple filters can be separated using a semicolon (ProcessPlan’s standard list delimiter.)

Here is an example.

/api/v4/process_instance_header/list/pending?take=10&skip=0&filter=th_name[ct]Test%20Process;ih_instance_description[ct]Test%20Description

The available filter operators include:

[ct] = contains (use OR in capital letters to add an OR condition to the [ct] filter operator).

[nct] = does not contain

[eq] = equal to

[neq] = not equal to

[sw] = starts with

[empty] = the property is empty

[hasvalue] = the property has a value

[range] = the property is within a range (dates and numbers - see below)

Choosing what an empty filter value does

With [eq], [ct] and the other operators above that take a value, a condition with an empty filter value is left out. These operators say what an empty value does instead. With a value, each one works exactly like [eq] or [ct]:

[eqreq] = equal to; an empty filter value matches nothing

[eqopt] = equal to; an empty filter value leaves the condition out

[eqblank] = equal to; an empty filter value matches records where the property is empty

[ctreq] = contains; an empty filter value matches nothing

[ctopt] = contains; an empty filter value leaves the condition out

They matter most when the filter value is a field token that may be blank, as in a process table lookup’s filter or a =TABLELOOKUP query. GET /invoice/list does not accept them and answers with an error.

A search that changes or links the records it finds, such as =INSTANCEUPDATE, never leaves a condition out: a blank [eqopt] or [ctopt] stops it instead. On a date field, [eqreq], [eqopt] and [eqblank] with a value match the date whatever its time, the same as [eq].

Filtering dates and date ranges

To filter a date property, use the [range] operator. The filter value has the form from..until - two date expressions separated by two periods. Either side may be left empty for an open-ended range. Leaving both sides empty matches nothing; to drop the date filter, leave the condition out. A range the server cannot read matches nothing either, and the response carries an Invalid Value message naming the property.

/api/v4/process_instance_header/list/pending?take=10&skip=0&filter=ih_created_date_local[range]now-7d..now

Each side of the range is either:

An absolute date: YYYY-MM-DD, optionally with a time (YYYY-MM-DDTHH:mm or YYYY-MM-DDTHH:mm:ss)
A relative expression: start with now, then optionally add or subtract amounts of time (+ / -) and/or snap to the start of a time unit (/)

The available time units are:

Unit	Meaning
`s`	seconds
`m`	minutes
`h`	hours
`d`	days
`w`	weeks
`M`	months
`Q`	quarters
`y`	years

Casing matters: lowercase m is minutes, capital M is months.

Relative expressions are evaluated left to right. For example, now/M-1M means “snap to the start of the current month, then go back one month” - in other words, the start of last month.

Common examples:

Filter value	Matches dates in…
`now-7d..now`	the last 7 days
`now/d..now/d+1d`	today
`now/d-1d..now/d`	yesterday
`now/w..now/w+1w`	this week
`now/w-1w..now/w`	last week
`now/M..now/M+1M`	this month
`now/M-1M..now/M`	last month
`now/Q-1Q..now/Q`	last quarter
`now/y..now/y+1y`	this year
`2026-01-01..2026-02-01`	all of January 2026
`2026-01-01..`	January 1, 2026 or later
`..now`	any date up to now

Date ranges include the start and exclude the end (from ≤ date < until), so consecutive ranges like “last month” and “this month” line up exactly with no gap or overlap.

URL-encode the filter value, and write any space as %20. ProcessPlan does not treat + as a space, so a + in a filter value is read as a literal plus sign. That means the + in a date expression works exactly as written:

filter=ih_created_date_local[range]now/M..now/M+1M

%2B is the encoded form of a plus sign, so this is equivalent:

filter=ih_created_date_local[range]now/M..now/M%2B1M

What will not work is using + in place of a space. th_name[ct]Test+Process searches for the literal text “Test+Process”; write th_name[ct]Test%20Process instead.

Filtering number ranges

The [range] operator also works for numeric properties. Numeric ranges include both ends (from ≤ value ≤ to), and either side may be left empty for an open-ended range. Both sides empty matches nothing, as with dates.

/api/v4/process_instance_header/list/pending?take=10&skip=0&filter=ih_progress_percentage[range]10..50

The following comparison operators can also be used for numeric properties.

/api/v4/process_instance_header/list/pending?take=10&skip=0&filter=ih_progress_percentage[gtn]0

[gte] = greater than or equal to

[gtn] = greater than or null

[gt] = greater than

[lte] = less than or equal to

[ltn] = less than or null

[lt] = less than