How to use filters

Filters allow you to specify the data you want to retrieve from Salsa's APIs. Regardless of which API you call, filters operate uniformly, and are applied with the filter parameter. For each filter, you must supply a fieldName and the value you wish to filter for.

Filter for a single value

When filtering string or enum fields with a single value, use the following request format:

GET /api/endpoint?filter[stringField]=value

This filter retrieves data where stringField matches the specified value.

Filter for multiple values

When filtering string fields for multiple values, values must be provided as an array. For example:

GET /api/endpoint?filter[stringField]=[value1, value2]

This filter retrieves data where stringField matches any of the specified values within the array (value1 or value2).

Filter for dates

For date fields, specific operators must be applied with the filter value:

onOrBefore(date): Retrieves objects with a date on or before the specified date.
onOrAfter(date): Retrieves objects with a date on or after the specified date.
onOrBetween(startDate, endDate): Retrieves objects where the date is within the range provided.

Example usage:

GET /api/endpoint?filter[dateField]=onOrBefore(2023-01-01)

Replace dateField with the appropriate date field in your API, and ensure to follow the correct syntax for the date operators.

Date interval fields

For fields containing date intervals (objects with startDate and endDate), use the contains(date) operator. For example:

GET /api/endpoint?filter[intervalField]=contains(2023-01-01)

Replace intervalField with the appropriate interval field in your API and ensure to follow the correct syntax for the date operators.

Apply multiple filters

Filters can be combined to further narrow down query results by using multiple filter parameters. For example:

GET /api/endpoint?filter[field1]=value1&filter[field2]=value2

Refer to the REST API documentation for a comprehensive list of available fields and their specific filtering capabilities.

How to sort responses

Sorting for list responses is achieved by specifying the field name of the value to be used to determine the order, as well as the direction of the sort (ascending or descending).

Field names are specified using the same syntax as filters, see details on the specification below.

To indicate the direction of the sort, you can prefix the field name with - in to indicate descending, otherwise the sort order will be ascending. For example, to sort paystubs by pay date in descending order, your request would look like this:

curl --request GET \
     --url 'https://api.sandbox.salsa.dev/api/rest/v1/employers/${employerId}/workers/${workerId}/worker-payment-records?page=0&size=500&sort=-payDate' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ADD_TOKEN'

Sorting with multiple criteria is also supported, and can be achieved by appending additional field names to the request. If no sorting criteria are specified, then the sort order of a list response is not guaranteed.

Field name specification

Field names within filters correspond to the field names in the REST response object.
Filters are case-sensitive; ensure accurate spelling and casing when applying filters.
For nested fields, the field name should be specified using dot notation. e.g. to refer to the payDate field that is a property of the payPeriod that is part of the resource, you would use payPeriod.payDate.