Filtering - Nomos

Every list endpoint supports filtering through query parameters in the form filter[<field>][<operator>]=<value>. Multiple filters combine with AND.

curl -G "https://api.nomos.energy/customers" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[type][eq]=person" \
  --data-urlencode "filter[created_at][gte]=2024-01-01T00:00:00Z"

The endpoint reference lists each filterable field and the operators it accepts. The tables below show the most each field type allows, and a field can accept fewer. A filter on an unknown field, an operator the field does not accept, the same filter sent twice, or more than one of eq, ne and in on one field returns 400 BAD_REQUEST, so a typo never returns the unfiltered list. An empty in list matches nothing.

Operators by field type

String
Number
Date
Boolean
Enum

Operator	Description	Example
`eq`	Exact match	`filter[email][eq]=john@example.com`
`ne`	Not equal	`filter[status][ne]=cancelled`
`in`	Comma-separated list	`filter[status][in]=active,pending`
`is_null`	Null check (`true`/`false`)	`filter[deleted_at][is_null]=true`
`contains`	Case-insensitive contains	`filter[last_name][contains]=mueller`
`starts_with`	Case-insensitive prefix	`filter[email][starts_with]=john`
`ends_with`	Case-insensitive suffix	`filter[email][ends_with]=@example.com`

Operator	Description	Example
`eq`	Equal to	`filter[amount][eq]=100`
`ne`	Not equal	`filter[amount][ne]=0`
`gt`	Greater than	`filter[amount][gt]=100`
`gte`	Greater than or equal	`filter[amount][gte]=100`
`lt`	Less than	`filter[amount][lt]=1000`
`lte`	Less than or equal	`filter[amount][lte]=1000`
`in`	Comma-separated list	`filter[amount][in]=10,20,30`
`is_null`	Null check	`filter[amount][is_null]=false`

Dates must be ISO 8601 with timezone.

Operator	Description	Example
`gte`	On or after	`filter[created_at][gte]=2024-01-01T00:00:00Z`
`lte`	On or before	`filter[created_at][lte]=2024-12-31T23:59:59Z`
`is_null`	Null check	`filter[terminated_at][is_null]=true`

Operator	Description	Example
`eq`	`true` / `false`	`filter[is_verified][eq]=true`
`is_null`	Null check	`filter[is_verified][is_null]=false`

Operator	Description	Example
`eq`	Exact match	`filter[status][eq]=active`
`ne`	Not equal	`filter[status][ne]=cancelled`
`in`	Comma-separated list	`filter[status][in]=active,pending`

The endpoint reference lists the allowed values for each enum field.

Common patterns

Filter by date range

curl -G "https://api.nomos.energy/subscriptions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[created_at][gte]=2024-01-01T00:00:00Z" \
  --data-urlencode "filter[created_at][lte]=2024-01-31T23:59:59Z"

Filter by multiple values

curl -G "https://api.nomos.energy/subscriptions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[status][in]=active,pending"

Search by substring

curl -G "https://api.nomos.energy/market-partners" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[name][contains]=stadtwerke"

Exclude ended subscriptions

curl -G "https://api.nomos.energy/subscriptions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[status][ne]=ended"

Combine with pagination

Pass the same filter parameters with each page when paginating:

curl -G "https://api.nomos.energy/subscriptions" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[status][eq]=active" \
  --data-urlencode "limit=20" \
  --data-urlencode "cursor=${NEXT_PAGE}"

Malformed filter syntax returns 400 BAD_REQUEST and an invalid value returns 422 UNPROCESSABLE_ENTITY, each with a message naming the offending parameter. See Errors for the full envelope.

​Operators by field type

​Common patterns

​Filter by date range

​Filter by multiple values

​Search by substring

​Exclude ended subscriptions

​Combine with pagination

Operators by field type

Common patterns

Filter by date range

Filter by multiple values

Search by substring

Exclude ended subscriptions

Combine with pagination