Overview

Filtering

The Awork API supports a wide range of filters that can be applied to most of our API endpoints.

A filter can be applied by adding a filterby expression to the request URL:

1/users?filterby=firstName eq 'Sebastian'

Important: Special characters (like ?, & and =) within a string filter value need to be properly URL encoded.

Correct:

1/companies?filterby=name eq 'awork %26 co'

Incorrect:

1/companies?filterby=name eq 'awork & co'

Use two single quotes to escape an apostrophe inside a string literal:

1/tasks?filterby=name eq 'user''s task'

If you want to filter by a nested property, you can do this by separating the properties by /, for example:

1/projects?filterby=company/name eq 'awork'

Logical Operations

You can invert the expression by using not before the statement

1/users?filterby=not firstName eq 'Sebastian'

Furthermore, you can combine expressions using the logical operator and

1/projects?filterby=plannedDuration le 200 and plannedDuration gt 3.5

as well as the logical operator or

1/projects?filterby=plannedDuration le 200 or plannedDuration gt 300

Precedence is defined with ( and ).

You can also use the any operator in combination with eq false to filter for items that do not contain a specific value.

1/tasks?filterby=lists/any(l: l/name eq 'Draft') eq false

Combining Filtering and Ordering

You can combine filtering and ordering by adding the orderby parameter to the URL.

1/projects?filterby=duration le 6000 and duration gt 1000&orderby=duration desc

Data Types

The data types DateTime and Guid have to be prefixed with the corresponding type identifier datetime and guid, respectively, e.g.

Filter by DateTime
1/users?filterby=birthDate ge datetime'2018-04-03T00:00'
Filter by Guid
1/users?filterby=id eq guid'12345678-aaaa-bbbb-cccc-ddddeeeeffff'
TypeExample
Nullnull
Booleantrue | false
Byte0x22
DateTimedatetime’2000-12-12T12:00’
Decimal2.345M
Double2.029
Single2.0f
Guidguid’12345678-aaaa-bbbb-cccc-ddddeeeeffff’
Int32
Long64L
String’Hello awork’

Operators

OperatorDescriptionQuery
eqThe eq operator filters and returns the items which match the filter term./users?filterby=firstName eq 'Neil'
neThe ne operator filters and returns the items which do not match the filter term./users?filterby=firstName ne 'Neil'
endswithThe endswith operator filters and returns the items which end with the filter term./users?filterby=endswith(firstName,'Neil')
startswithThe startswith operator filters and returns the items which start with the string./users?filterby=startswith(firstName,'Neil')
substringofThe substringof operator filters and returns the items which contain the filter term./users?filterby=substringof('Neil',firstName)
gtThe gt operator filters and returns the items which are greater than the filter term./users?filterby=birthDate gt datetime'2018-04-03T00:00'
ltThe lt operator filters and returns the items which are less than the filter term./users?filterby=birthDate lt datetime'2018-04-03T00:00'
leThe le operator filters and returns the items which are less than or equal to the filter term./users?filterby=birthDate le datetime'2018-04-03T00:00'
geThe ge operator filters and returns the items which are greater than or equal to the filter term./users?filterby=birthDate ge datetime'2018-04-03T00:00'
inThe in operator filters and returns the items where the property value matches any value in the provided list./tasks?filterby=tags/any(t: t/name in ('Draft','In Progress'))
anyThe any operator iterates through the main entity (Project), executes the condition and returns the filtered list of projects where any member with a first name of ‘Neil’ exists./projects?filterby=members/any(p: p/firstName eq 'Neil')
countThe count operator iterates through the main entity (Project), and returns the filtered list of projects that have less than 10 members. Also supports conditional counting with expressions./projects?filterby=members/count() lt 10 or /projects?filterby=members/count(m: m/firstName eq 'Neil') gt 0
tolowerThe tolower operator can be used to convert strings to lowercase, which can be helpful for string comparison./projects?filterby=tolower(name) eq 'website'
Not all operators can be used in combination or nested.

Special Operator for the Current User

ExpressionDescriptionExample
me.idFilters for the current user/users?filterby=id eq me.id

Special Operators for Date and Time

ExpressionDescriptionExample
nowFilters for less than current date-time/tasks?filterby=dueOn lt now
sowFilters for greater than start of week/tasks?filterby=dueOn gt sow
eowFilters for greater than end of week/tasks?filterby=dueOn gt eow
somFilters for greater than start of month/tasks?filterby=dueOn gt som
eomFilters for greater than end of month/tasks?filterby=dueOn lt eom
todayFilters for today/tasks?filterby=dueOn eq today
today-30dFilters for a relative date in the past/tasks?filterby=dueOn gt today-30d
today+5dFilters for a relative date in the future/tasks?filterby=dueOn gt today+5d