> For the complete documentation index, see [llms.txt](https://developers.spiffy.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.spiffy.co/api/getting-started/filtering.md).

# Filtering

Most list endpoints support filtering to narrow results. Filters use a dot notation syntax for operators:

| Syntax                             | Operator                    | Example                                |
| ---------------------------------- | --------------------------- | -------------------------------------- |
| `?filter[field]=value`             | Exact match                 | `?filter[status]=active`               |
| `?filter[field.contains]=value`    | Contains (case-insensitive) | `?filter[email.contains]=gmail`        |
| `?filter[field.gt]=value`          | Greater than                | `?filter[amount.gt]=100`               |
| `?filter[field.gte]=value`         | Greater than or equal       | `?filter[created_at.gte]=2025-01-01`   |
| `?filter[field.lt]=value`          | Less than                   | `?filter[amount.lt]=500`               |
| `?filter[field.lte]=value`         | Less than or equal          | `?filter[updated_at.lte]=2025-12-31`   |
| `?filter[field.in]=value1,value2`  | In list                     | `?filter[status.in]=active,trialing`   |
| `?filter[field.nin]=value1,value2` | Not in list                 | `?filter[status.nin]=canceled,expired` |

**Complex example:**

```
GET /v2/customers?filter[email.contains]=john&filter[created_at.gte]=2025-01-01&filter[status]=active
```

This finds active customers with "john" in their email address created after January 1st, 2025.

#### Unrecognized parameters are ignored, not rejected

Filtering, expansion, search and sort all fail open. A filter key that is not supported for a resource, an `include=` value that does not exist, `search=` on an endpoint with no searchable fields, and `sort=` on a field that is not sortable are each dropped silently. The request returns **200** with a normal body — unfiltered, or unexpanded.

This is worth designing around, because nothing in the response tells you it happened: a filter that looks reasonable but is not in the parameter list for that specific endpoint will return your entire table, one page at a time, and the code will look correct. Check the parameters documented for the exact endpoint you are calling rather than assuming a field that exists on the object is filterable.

Values are validated once a key is recognized — an unknown enum value returns **400** listing the valid ones, and a malformed date or number returns **400** naming the field.
