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'

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

Data Types

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

  • /users?filterby=birthDate ge datetime'2018-04-03T00:00'
  • /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'
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./projects?filterby=members/count() lt 10
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