Filters

Most EnergyCAP list endpoints support a filter query parameter that lets you narrow results server-side instead of fetching everything and filtering in your code. Each endpoint’s documentation lists its available filter fields and supported operators.

Syntax

A filter is one or more expressions joined by and:

filter=<field> <operator> '<value>'
filter=<field> <operator> '<value>' and <field> <operator> '<value>'

Every value must be single-quoted, even numbers and booleans.

Operators

Comparison Operators

These work with strings, numbers, and dates.

Operator	Description	Example
`equals`	Exact match	`accountId equals '1234'`
`not equals`	Not equal to	`active not equals 'true'`
`less than`	Less than	`totalCost less than '500'`
`greater than`	Greater than	`totalCost greater than '100'`
`less than equal`	Less than or equal	`totalCost less than equal '500'`
`greater than equal`	Greater than or equal	`totalCost greater than equal '100'`

Text Operators

These work with string fields and support wildcard matching.

Operator	Description	Example
`like`	Contains (wildcard match)	`accountInfo like 'Main Campus'`
`not like`	Does not contain	`accountCode not like 'TEST'`

Multi-Value Operators

Match against a list of values separated by | (pipe).

Operator	Description	Example
`one of`	Matches any value in the list	`accountId one of '1234'\|'5678'\|'9012'`
`not one of`	Matches none of the values	`vendorCode not one of 'V001'\|'V002'`

Range Operator

Match values within a range using two values separated by |.

Operator	Description	Example
`between`	Inclusive range	`totalCost between '100'\|'500'`
`not between`	Outside the range	`totalCost not between '100'\|'500'`

Date Shortcut Operators

These operators work on date fields and require no value — they calculate the range automatically.

Operator	Description
`today`	Today’s date
`yesterday`	Yesterday’s date
`last 7 days`	Past 7 days
`last 14 days`	Past 14 days
`last 30 days`	Past 30 days
`last 60 days`	Past 60 days
`last 90 days`	Past 90 days
`current month`	Current calendar month
`prior month`	Previous calendar month
`prior year`	Previous calendar year
`prior fiscal year`	Previous fiscal year
`year-to-date*`	Start of current year through today
`year-to-date**`	Start of current year through end of prior month
`fiscal year-to-date*`	Start of current fiscal year through today
`fiscal year-to-date**`	Start of current fiscal year through end of prior month
`prior 12 months*`	12 months ending today
`prior 12 months**`	12 months ending at end of prior month

Date shortcuts are used without a value:

filter=serviceBegin last 30 days

Combining Expressions

Join multiple expressions with and to create compound filters. All conditions must be true for a record to be included.

filter=accountId equals '1234' and active equals 'true'

There is no or operator. If you need “or” logic, use the one of operator for a single field, or make separate API calls.

Real-World Examples

Get all bills for a specific account

curl -X GET "https://app.energycap.com/api/v3/bill?filter=accountId equals '1234'" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get accounts matching a name pattern

curl -X GET "https://app.energycap.com/api/v3/account?filter=accountInfo like 'Main Campus'" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get bills for multiple accounts

curl -X GET "https://app.energycap.com/api/v3/bill?filter=accountId one of '1234'|'5678'|'9012'" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get bills within a cost range for a specific vendor

curl -X GET "https://app.energycap.com/api/v3/bill?filter=totalCost between '100'|'500' and vendorCode equals 'DUKE_ENERGY'" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get accounts with service starting in the last 30 days

curl -X GET "https://app.energycap.com/api/v3/account?filter=serviceBegin last 30 days" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get batches created between two dates

curl -X GET "https://app.energycap.com/api/v3/batch?filter=endDate between '2025-01-01'|'2025-06-30'" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

Get inactive bills for a specific meter group

curl -X GET "https://app.energycap.com/api/v3/bill?filter=active equals 'false' and meterGroupCode equals 'CAMPUS_NORTH'" \
  -H "ECI-ApiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json"

URL Encoding

When sending filters as query parameters, special characters must be URL-encoded. Most HTTP client libraries handle this automatically, but if you’re constructing URLs manually:

Character	Encoded
Space	`%20`
Single quote `'`	`%27`
Pipe `\|`	`%7C`

For example, this filter:

filter=accountInfo like 'Main Campus'

Becomes:

?filter=accountInfo%20like%20%27Main%20Campus%27

Tip

Most HTTP libraries and tools (curl, Postman, SDKs) URL-encode query parameters automatically. You typically only need to worry about encoding if you’re building raw URLs in code.

Escaping Special Characters

To include a literal single quote in a filter value, escape it with a backslash:

filter=accountInfo like 'O\'Brien'

Tips

Check the endpoint documentation — each endpoint lists its filterable fields and which operators are supported for each field. Not all operators work on all fields.
Combine with pagination — filters reduce the total result set, which means fewer pages to iterate through. See Pagination.
Combine with field reduction — use filters to select which records and field reduction to select which fields, minimizing both the number of results and the size of each response.
Boolean fields only support equals — use 'true' or 'false' as the value.
Date values should be formatted as 'YYYY-MM-DD' (e.g. '2025-01-15').