Filtering

Filtering

Most list endpoints in the Fenerum API accept query-string filters to narrow down the result set. The exact set of filters supported by each endpoint is listed in the Parameters section of that endpoint's reference page — the description below covers the conventions used across all of them.

Exact-match filters

Filter by a specific field value:

GET /api/v1/invoices/?status=open

GET /api/v1/accounts/?code=CUST001

Multiple filters can be combined; they are AND-ed together:

GET /api/v1/invoices/?status=due&collection_method=invoice

Comparison filters

For numeric and date fields, Fenerum exposes Django-style lookup suffixes:

Date filters accept ISO date strings (YYYY-MM-DD).

Date-range example

Get invoices created in December 2025:

GET /api/v1/invoices/?created_date__gte=2025-12-01&created_date__lt=2026-01-01

Negated filters

A few endpoints expose _not variants for exclude-style queries. Check the endpoint's Parameters for what's available, for example on Invoices:

GET /api/v1/invoices/?status_not=paid&account_not=CUST001

Combining with pagination

Filters are preserved across pages — the next/previous URLs in a paginated response carry your filter parameters forward. See Pagination for the page/page_size envelope.

GET /api/v1/invoices/?account=CUST001&page=2&page_size=50

The count field in the response reflects the total filtered result count, not the unfiltered total.

Looking up by alternative identifier

A small set of endpoints (currently Plans and Plan Terms) accept a Lookup-Field HTTP header that switches how the URL path identifier is interpreted — useful when you don't have the UUID but do know the resource's external code:

GET /api/v1/plans/enterprise/
Lookup-Field: code

Allowed values are documented on the affected endpoints (typically uuid and code).

Best practices

• Filter before paginating. Pulling smaller result sets is faster and counts against your rate limit less.
• Use ISO dates. All date fields accept YYYY-MM-DD; some also accept ISO datetimes (YYYY-MM-DDTHH:MM:SSZ).
• Check the endpoint's parameters. Filter names vary per resource — the Parameters block on each operation lists exactly what's available (look for the blue query badge).