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

# Filtering and query parameters

> Filter API results by date range, utility type, site, and other criteria.

Most list endpoints in the Nectar API accept query parameters to filter the results. This guide covers the most commonly used filters.

## Usage data filters

The usage data endpoints (`/usage/company/{id}`, `/usage/site/{id}`, etc.) support the following filters:

| Parameter        | Type   | Description                                                  | Example              |
| ---------------- | ------ | ------------------------------------------------------------ | -------------------- |
| `startDate`      | Date   | Filter by start boundary (behavior depends on `dateType`)    | `2025-01-01`         |
| `endDate`        | Date   | Filter by end boundary (behavior depends on `dateType`)      | `2025-12-31`         |
| `dateType`       | String | Which date field to filter on (default: `BILL_DATE`)         | `USAGE_PERIOD`       |
| `datasourceType` | String | Filter by utility type (accepts multiple values)             | `ELECTRICITY`, `GAS` |
| `identifier`     | String | Search across all meter identifiers (normalized — see below) | `0137746423`         |

### Date type values

| Value          | Description                                          |
| -------------- | ---------------------------------------------------- |
| `BILL_DATE`    | Filter by the invoice date on the document (default) |
| `USAGE_PERIOD` | Filter by the usage period start and end dates       |
| `CREATED_DATE` | Filter by when the record was created                |
| `UPDATED_DATE` | Filter by when the record was last updated           |

<CodeGroup>
  ```bash cURL theme={null}
  curl -X GET 'https://external.nectarclimate.com/v2.2/usage/company/{companyId}?startDate=2025-01-01&endDate=2025-12-31&datasourceType=ELECTRICITY' \
    -H 'X-API-Key: YOUR_SECRET_KEY'
  ```

  ```python Python theme={null}
  import requests

  response = requests.get(
      f"https://external.nectarclimate.com/v2.2/usage/company/{company_id}",
      headers={"X-API-Key": "YOUR_SECRET_KEY"},
      params={
          "startDate": "2025-01-01",
          "endDate": "2025-12-31",
          "datasourceType": "ELECTRICITY",
      },
  )
  usage_data = response.json()
  ```
</CodeGroup>

### Commodity types

Use these values for the `datasourceType` parameter:

| Value           | Commodity                    |
| --------------- | ---------------------------- |
| `ELECTRICITY`   | Electricity                  |
| `GAS`           | Natural gas                  |
| `WATER`         | Water                        |
| `WASTE`         | Waste                        |
| `FUEL`          | Fuel (diesel, propane, etc.) |
| `SOLAR`         | Solar                        |
| `SEWER`         | Sewer                        |
| `STEAM`         | Steam (district)             |
| `CHILLED_WATER` | Chilled water (district)     |
| `HOT_WATER`     | Hot water (district)         |

### Identifier matching

The `identifier` filter normalizes both the search value and stored identifiers before comparing. Normalization removes dashes, spaces, underscores, commas, and forward slashes, strips leading zeros, and converts to uppercase. This means:

* `013-774-6423` matches `0137746423`
* `137746423` matches `0137746423` (leading zeros are ignored)

## Document filters

Document endpoints (`/document/company/{id}`, `/document/site/{id}`, etc.) support the same date, `dateType`, `datasourceType`, and `identifier` filters as usage data endpoints. Additionally:

| Parameter   | Type    | Description                                       |
| ----------- | ------- | ------------------------------------------------- |
| `isDeleted` | Boolean | Include soft-deleted documents (default: `false`) |

## Connection filters

Connection endpoints (`/connection/company/{id}`) support owner, status, and site filters:

| Parameter              | Type              | Description                                                           |
| ---------------------- | ----------------- | --------------------------------------------------------------------- |
| `connectionOwnerEmail` | String (email)    | Filter by exact connection owner email                                |
| `sites`                | UUID (repeatable) | Filter to connections linked to one or more sites                     |
| `status`               | String            | Filter by connection status (e.g., `CONNECTED`, `PASSWORD_INCORRECT`) |

See [Connection statuses](/developer-guide/connection-statuses) for the full list of status values.

```bash theme={null}
# Filter by owner and site
curl -X GET 'https://external.nectarclimate.com/v2.2/connection/company/{companyId}?connectionOwnerEmail=owner@example.com&sites={siteId}' \
  -H 'X-API-Key: YOUR_SECRET_KEY'
```

## Combining filters with pagination

All filters work alongside [pagination](/developer-guide/pagination) parameters. The total in the response reflects the filtered count, not the unfiltered total.

```bash theme={null}
# Get page 2 of electricity usage data for 2025
curl -X GET 'https://external.nectarclimate.com/v2.2/usage/company/{companyId}?startDate=2025-01-01&endDate=2025-12-31&datasourceType=ELECTRICITY&page=2' \
  -H 'X-API-Key: YOUR_SECRET_KEY'
```

## Next steps

<CardGroup cols={2}>
  <Card title="Pagination" icon="arrow-right" href="/developer-guide/pagination">
    Iterate through large result sets
  </Card>

  <Card title="API Reference" icon="square-terminal" href="/api-reference">
    Full parameter documentation for every endpoint
  </Card>
</CardGroup>