What is API Filtering?
API filtering is functionality that allows client applications to specify precisely what kind of data they need returned from the Paylocity API. Instead of returning an entire dataset, Paylocity’s APIs with filtering capabilities send only a subset that fits specific criteria defined by the client. This significantly enhances the efficiency and speed of data transfer, as it reduces the bandwidth and processing power required both on the server and client-side. This will also limit the transfer of PII.
Principles of Paylocity API Filtering
API filtering works on the principle of request-response communication. The client makes a request to the server, specifying the filter criteria in the request. The server processes this request, applies the filter, and sends back only the data that meets the criteria.
Certain APIs on the Paylocity API Platform provide an additional query parameter called filter. This allows filtering by a resource's value beyond just the equals operator (i.e., greater than, less than, etc.), including filtering by nested attributes. The supported fields and operators list is documented on each API-specific filtering page.
Filter Syntax:
| Operator | Description | Example Usage |
|---|---|---|
| eq | Equal | firstName eq 'John' |
| ne | Not equal | firstName ne 'John' |
| gt | Greater than | hourlyWage ge 25 |
| ge | Greater than or equal | hourlyWage ge 25 |
| lt | Less than | hourlyWage lt 25 |
| le | Less than or equal | hourlyWage le 50 |
| in | Equals any of the values provided | firstName in ('John', 'Jack') |
| ct | Contains the values provided (use carefully and watch performance) | title ct 'Engineer' |
| sw | Starts with the value provided (use carefully and watch performance) | salutation sw 'Honour' |
| cv | Array attribute contains an element whose value equals the value provided | aliases cv 'OJ' |
Examples:
Example: ?filter=firstName eq George would filter where the firstName attribute is equal to George
Logical AND or OR can be used within an individual filter, and parenthesis can denote precedence in filters.
Example: filter=age gt 10 AND age lt 60 would filter where age is between 10 and 60 (non-inclusive)
Example: filter=age gt 60 OR age lt 10 would filter where age is greater than 60 or less than 10 (non-inclusive)
Example: filter=(age gt 60 OR age lt 10) AND status eq Active would filter where age is greater than 60 or less than 10 (non-inclusive) and also only include results where the status is active