Skip to main content
All list endpoints support filtering through query parameters. Nomos uses bracket notation for filters: filter[field][operator]=value.

​
Query Format

filter[<field>][<operator>]=<value>
Multiple filters are combined with AND logic.

​
Example

Filter active customers created after January 2024: 
curl "https://api.nomos.energy/v2/customers?filter[status][eq]=active&filter[created_at][gte]=2024-01-01T00:00:00Z" \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

​
Operators by Field Type

Available operators depend on the field type. Each endpoint documents which fields are filterable.

​
String Fields

OperatorDescriptionExample
eqExact matchfilter[email][eq]=john@example.com
neNot equalfilter[status][ne]=cancelled
containsCase-insensitive containsfilter[last_name][contains]=doe
starts_withCase-insensitive prefixfilter[email][starts_with]=john
ends_withCase-insensitive suffixfilter[email][ends_with]=@example.com

​
Number Fields

OperatorDescriptionExample
eqEqual tofilter[amount][eq]=100
neNot equalfilter[amount][ne]=0
gtGreater thanfilter[amount][gt]=100
gteGreater than or equalfilter[amount][gte]=100
ltLess thanfilter[amount][lt]=1000
lteLess than or equalfilter[amount][lte]=1000

​
Date Fields

Dates must be in ISO 8601 format with timezone.
OperatorDescriptionExample
gteOn or afterfilter[created_at][gte]=2024-01-01T00:00:00Z
lteOn or beforefilter[created_at][lte]=2024-12-31T23:59:59Z

​
Boolean Fields

OperatorDescriptionExample
eqTrue or falsefilter[is_verified][eq]=true

​
Filterable Fields by Endpoint

Each endpoint supports a specific set of filterable fields. Refer to the OpenAPI spec for full operator details.
EndpointFilterable Fields
/subscriptionsstatus (string), customer (string), plan (string), created_at (date), updated_at (date)
/customersemail (string), type (string), created_at (date)
/leadscreated_at (date)
/subscriptions/{id}/invoicesstatus (string), period_start (date), period_end (date)
/plansstatus (string), created_at (date)
/subscriptions/{id}/meter_readingstype (string), created_at (date)
/suppliersname (string), code (string), created_at (date)
/grid-fee-reductionsstatus (string), customer (string), subscription (string), created_at (date), updated_at (date)
/meter-ordersstatus (string), product (string), customer (string), subscription (string), created_at (date), updated_at (date)

​
Common Use Cases

​
Date Range

Get subscriptions created in January 2024: 
curl "https://api.nomos.energy/v2/subscriptions?filter[created_at][gte]=2024-01-01T00:00:00Z&filter[created_at][lte]=2024-01-31T23:59:59Z" \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

​
Multiple Values

Get customers with specific statuses: 
curl "https://api.nomos.energy/v2/customers?filter[status][in]=active,pending" \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

​
Text Search

Find customers with last name containing “Mueller”: 
curl "https://api.nomos.energy/v2/customers?filter[last_name][contains]=Mueller" \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

​
Non-Terminated Records

Get active subscriptions (not terminated): 
curl "https://api.nomos.energy/v2/subscriptions?filter[terminated_at][is_null]=true" \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

​
Combined with Pagination

Filters work seamlessly with pagination. Keep the same filter parameters when paginating: 
curl "https://api.nomos.energy/v2/subscriptions?filter[status][eq]=active&limit=20&cursor=xxxx" \
  --header 'Authorization: Bearer YOUR_SECRET_TOKEN'

​
Error Handling

Invalid filters return a 400 Bad Request with details about the issue.

​
Unknown Field

{
  "code": "VALIDATION_ERROR",
  "message": "Unknown filter field: 'unknown_field'"
}

​
Invalid Operator

{
  "code": "VALIDATION_ERROR",
  "message": "Operator 'contains' not allowed for field 'created_at' (type: date)"
}

​
Malformed Syntax

{
  "code": "VALIDATION_ERROR",
  "message": "Invalid filter syntax: 'filter[status]'. Expected format: filter[field][operator]=value"
}