Filtering results

📘

Finding which fields can you filter on

Not all fields are able to be filtered - to find which fields you can filter on you should go to the "GET ALL" route for the endpoint and check the table under the code sample block.

If there are no fields listed, then you cannot filter that endpoint.

Basic usage example

https://api02.naturalhr.net/api/v1/time-off?filter_groups[0][filters][0][0]=start_date&filter_groups[0][filters][0][1]=eq&filter_groups[0][filters][0][2]=2018-10-30

The filter element of the URL is broken into 3 parts:

  1. Field name
  2. Comparison operator
  3. Value

In the above example URL, this is broken down into:

filter_groups[0][filters][0][0]=start_date
&
filter_groups[0][filters][0][1]=eq
&
filter_groups[0][filters][0][2]=2018-10-30
  1. Element 0 is the field name – start_date in this instance
  2. Element 1 is the comparison operator – equals in this instance
  3. Element 2 is the filter value – 2018-10-30 in this instance

This filter, therefore, would return all time off with a start date equal to 2018-10-30.

Filtering on more than one field

If you need to filter on more than one field, you can append an additional array element to the query string.

For example, below we have filter_groups[0][filters][0] for the start_date and then filter_groups[0][filters][1] for time_off_type:

filter_groups[0][filters][0][0]=start_date
&
filter_groups[0][filters][0][1]=eq
&
filter_groups[0][filters][0][2]=2018-10-30
&
filter_groups[0][filters][1][0]=time_off_type
&
filter_groups[0][filters][1][1]=eq
&
filter_groups[0][filters][1][2]=Holiday

This filter, therefore, would return all time off with a start_date equal to 2018-10-30 AND where the time_off_type equals ‘Holiday’

Using JSON array for filters

As well as passing query parameters into the URL, you can also send a JSON array for filters. This uses the same logic as above so, using the example above with two parameters this would look like:

{ 
    "filter_groups": [
        { 
            "filters": [
                ["start_date", "eq", "2018-10-30"], 
                ["time_off_type", "eq", "Holiday"]
            ] 
        }
    ] 
}

Logical operators

By default the filter will use AND for the logical operator when you have more than 1 parameter.
You can change this to an OR operator by using the below in the relevant filter group:
filter_groups[0][or]=true

Supported comparison operators

Filter

Usage

eq

Equals

gt

Greater than

gte

Greater than or equal to

lt

Less than

lte

Less than or equal to

ct

Contains