Filtering

When requesting a collection of resources the resulting list can be reduced by passing one or more filter conditions:

$ curl https://api.4me.com/v1/requests?status=assigned\
       &next_target_at=>2011-10-01T00:00:00Z

Multiple conditions are joined using AND. The following operators can be used in filter conditions:

equality
Same as given value

?id=43523 or ?name=foo

negation
Different from given value

?status!=assigned or ?team_id=!4

empty
Has no value (null)

?team_id= or ?remarks=

present
Contains a value (not null)

?team_id!= or ?remarks=!

in
Equal to one of the given values (integers and enums only)

?id=1,2,3,4 or ?ids=1,2,3,4 or ?status=assigned,accepted

not in
Not equal to one of the given values (integers and enums only)

?id!=1,2,3,4 or ?ids!=1,2,3,4 or ?id=!1,2,3,4 or ?status!=assigned,accepted

less than
Less than given value (not for enums, strings and booleans)

?created_at=<2016-01-15T23:00:00Z or ?purchase_value=<90.00

less than or equal to
Less than or equal to given value (not for enums, strings and booleans)

?warranty_expiry_date=<=2016-01-15 or ?nr_of_licenses=<=30

greater than
Greater than given value (not for enums, strings and booleans)

?completed_at=>2016-01-15T23:00:00Z or ?nr_of_processors=>2

greater than or equal to
Greater than or equal to given value (not for enums, strings and booleans)

?updated_at=>=2016-01-15T23:00:00Z or ?salvage_value=>=100.00

greater than and less than
Greater than given value and less than the other given value(not for enums, strings and booleans)

?date=>2015-12-31<2016-02-01 or ?assignment_count=>3<10

greater than or equal to and less than or equal to
Greater than or equal to given value and less than or equal to the other given value(not for enums, strings and booleans)

?date=>=2016-01-01<=2016-01-31 or ?assignment_count=>=4<=9

For date time target fields like response_target_at, resolution_target_at and next_target_at, the following special values are also accepted: best_effort, clock_stopped, no_target.

See the Data Types section for more information on the formatting of input values.

Filter Exceptions

Not all combinations of filters are allowed and not all operators can be used on all fields. In case an invalid filter condition is applied a Bad Request response will be returned.

Status: 400 Bad Request
Content-Type: application/json; charset=utf-8
{
  "message": "..."
}

Some example messages are:

Most available fields for each model can be used in filters, but at least one field should be indexed. If none of the filter conditions reference an indexed field, the following error message will be shown:

Predefined Filters

Most models have predefined filters, similar to the state buttons and views found in the 4me UI. They can be applied by appending /<predefined_filter> to the URI path:

$ curl https://api.4me.com/v1/requests/open

Alternatively, the ?state= parameter can be used to apply a predefined filter:

$ curl https://api.4me.com/v1/requests?state=open

$ curl https://api.4me.com/v1/requests/requested_by_or_for_me?state=open

It is possible to combine predefined filters and filter conditions.

It is also possible to use predefined filters to look up only certain relations of a specific record. This make it possible to, for example, look up the open requests that are linked to a change, or the internal notes of a request.

$ curl https://api.4me.com/v1/changes/:id/requests/open

$ curl https://api.4me.com/v1/requests/:id/notes/internal