> ## Documentation Index
> Fetch the complete documentation index at: https://developers.luccasoftware.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Filtering

> Learn how to return a subset of a collection's items.

## Introduction

Most collection API endpoints support filtering, which makes it possible to retrieve a subset of resources by applying conditions on their state. For example, you can only retrieve leave objects whose status is `tentative`.

Filtering is commonly handled through query parameters: `/lucca-api/leaves?status=tentative`.

Some query parameters support lists, in which case the server expects a comma-separated list of values: `?status=tentative,confirmed`.

As of now, only strict equality or inequality filters are supported outside of dates, date-times and date-time-offsets. Filters are most often named with the corresponding property. For inequality filters, the property name is prefixed with the "-" character.

<CodeGroup>
  ```http Equality theme={null}
  # Retrieve all leaves with status "tentative"
  GET /lucca-api/leaves?status=tentative HTTPS/2
  ```

  ```http Inequality ("-" prefix) theme={null}
  # Retrieve all leaves with a status different from "tentative"
  GET /lucca-api/leaves?-status=tentative HTTPS/2
  ```
</CodeGroup>

<Warning>
  You can only filter on a subset of the object properties.

  Filtering is implemented on an opt-in basis: each endpoint only supports filtering on a preset of properties. If you feel like a filter is missing, please contact us.
</Warning>

***

## Dates, Date-Times and Date-Time-Offsets

When filtering on date, date-time or date-time-offset properties, you may:

1. Apply a strict equality filter through a query parameter whose name exactly matches the name of the property.
2. Apply an "intersection" filter through a query parameter whose name is `{propertyName}.between`.

In this second case, the query parameter value [must conform to a date-range, a date-time-range or a date-time-offset-range](./data-types#date-ranges),
depending on the type of the attribute.

For example, retrieving all leave resources which were created between 04:00 PM and 08:00 PM (UTC) on Jan. 1<sup>st</sup> 2023:

<CodeGroup>
  ```http Strict Equality theme={null}
  GET /lucca-api/leaves?startsOn=2024-01-01 HTTPS/2
  Host: example.ilucca.net
  Api-Version: {API_VERSION}
  Authorization: Bearer {ACCESS_TOKEN}
  Accept: application/json
  Accept-Encoding: gzip, br
  ```

  ```http Between two dates theme={null}
  GET /lucca-api/leaves?createdAt.between=2023-01-01T16:00:00Z--2023-01-01T20:00:00Z HTTPS/2
  Host: example.ilucca.net
  Api-Version: {API_VERSION}
  Authorization: Bearer {ACCESS_TOKEN}
  Accept: application/json
  Accept-Encoding: gzip, br
  ```
</CodeGroup>

Please note that open-ended ranges are supported through the ".." characters: `?createdAt=..--2023-01-01T20:00:00Z` (all leaves created before Jan. 1<sup>st</sup> 2023 at 08:00 PM UTC).

More examples:

* `2024-01-01--2024-12-31`: from Jan. 1st 2024 until Dec. 31st 2024 (included).
* `..--2024-12-31`: until Dec. 31st 2024.
* `2024-01-01--..`: from Jan. 1st 2024.