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]=residential" \
  --data-urlencode "filter[created_at][gte]=2024-01-01T00:00:00Z"

The endpoint reference lists each filterable field and which operators it accepts. Available operators are determined by the field’s type. Filters that name an unknown field or use a disallowed operator are silently ignored, so a typo’d field name returns the unfiltered list rather than an error.

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`
`is_null`	Null check	`filter[status][is_null]=true`

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/customers" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[status][in]=active,pending"

Search by substring

curl -G "https://api.nomos.energy/customers" \
  -H "Authorization: Bearer ${ACCESS_TOKEN}" \
  --data-urlencode "filter[last_name][contains]=mueller"

Exclude terminated records

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

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 or invalid values return 400 BAD_REQUEST 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 terminated records

​Combine with pagination

Operators by field type

Common patterns

Filter by date range

Filter by multiple values

Search by substring

Exclude terminated records

Combine with pagination