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

# Filtering

> Narrow, search, and sort list results with query parameters, and how the available filters differ by endpoint.

List endpoints accept query parameters that narrow the results to the records you want — by identifier, by type, by date, and more. Which filters an endpoint offers differs from endpoint to endpoint, so each endpoint's reference page is the source of truth for what it accepts.

## How filtering works

Filters are query parameters on a list request. Combine several to narrow the results further:

```bash theme={null}
curl "https://api.spirii.com/v2/transactions?locationId=12345&transactionType=nonRoaming" \
  -H "Authorization: Bearer <SPIRII_API_KEY>"
```

Values follow the endpoint's schema: enums must match the reference exactly and are case-sensitive, IDs are numbers or strings, and timestamps are ISO 8601. Filtering pairs with [pagination](/developers/pagination) — the filters decide *which* records are returned, and pagination controls how you page through them.

## Common filter patterns

The same families of filter recur across the API. The parameter names and accepted values are endpoint-specific, but the shapes below are what you'll meet.

### By identifier

Return only the records matching one or more IDs. Some endpoints take a single value:

```
/v2/transactions?locationId=12345
```

Others take a list — repeat the parameter once per value (confirm the exact form on the endpoint's reference page):

```
/v2/chargeboxes?locationIds=12345&locationIds=67890
```

### By type or status

Enum filters restrict results to a fixed set of values, such as a transaction type (`nonRoaming`, `roamingCpo`) or a location type (`PublicRoad`, `Residential`). Match the value exactly as the reference lists it.

### Flags

Boolean filters toggle a subset on or off — for example `ongoing` for transactions still in progress, or `isActive` for active tokens:

```
/v2/tokens?isActive=true
```

### Date and time ranges

Filter by a timestamp to return records from — or up to — a point in time, using ISO 8601:

```bash theme={null}
curl "https://api.spirii.com/v2/transactions?startedAt=2025-01-01T00:00:00.000Z&endedAtMax=2025-01-31T23:59:59.000Z" \
  -H "Authorization: Bearer <SPIRII_API_KEY>"
```

On some endpoints, applying a date filter also sets the default sort order — check the parameter's description in the reference.

### Search

Where an endpoint supports free-text search, a `search` parameter matches across a few fields at once. On tokens, for example, it matches the token ID, label, or UID:

```
/v2/tokens?search=DK.SPI
```

### Sorting

A `sortBy` parameter chooses the field to order by. Some endpoints add a separate `sortDirection` (`asc` or `desc`); others fix the direction:

```
/v2/tokens?sortBy=createdAt&sortDirection=desc
```

## Filters vary by endpoint

The reference for each endpoint lists its exact filters — treat it as authoritative. A few differences are worth checking before you depend on a filter across several endpoints:

* **One value or a list.** The same idea appears as a single `locationId` on one endpoint and a `locationIds` list on another.
* **Flag values.** Most flags are `true` / `false`, but a few take `0` / `1`.
* **Date-range naming.** The lower bound is usually named for the field (`startedAt`, `validFrom`); the upper bound is named less consistently (`endedAtMax`, for instance). Read both ends off the reference rather than assuming a pattern.
* **Sorting.** Whether you can set the direction — and the default when you don't — depends on the endpoint.
* **Deprecated filters.** Where the reference marks a parameter deprecated, prefer the current one it points to (for example `customerIds` in place of `customerId`).

<Info>
  If your integration filters across several endpoints, read each filter off its reference page rather than reusing a name that worked elsewhere. The families are consistent; the exact parameters are not.
</Info>

## Related

<CardGroup cols={2}>
  <Card title="Pagination" icon="layers" href="/developers/pagination">
    Page through filtered results reliably.
  </Card>

  <Card title="API reference" icon="square-terminal" href="/api-reference/overview">
    The exact filters each endpoint accepts.
  </Card>
</CardGroup>