Introducing Advanced Filtering, Sorting and Aggregation in the EventWorks API

We’ve shipped a major upgrade to the EventWorks v2 API that gives you powerful, flexible ways to query your data. Whether you’re building dashboards, generating reports, or integrating with third-party tools, the new query system puts you in full control of what data you get back and how it’s shaped.

JSON Filter Syntax

Every list endpoint now supports a rich JSON filter syntax with 18 comparison operators. You can filter on direct fields, related resources, and combine conditions with AND/OR logic to any depth.

Simple equality:

GET /api/v2/events?filter={"event_status_id":{"_eq":3}}

Date ranges:

GET /api/v2/events?filter={"start_date":{"_between":["2026-01-01","2026-06-30"]}}

Complex logic — contracted events above 10k OR any event managed by a specific user:

{
  "_or": [
    {
      "_and": [
        {"status.is_contracted": {"_eq": true}},
        {"reported_price": {"_gte": 10000}}
      ]
    },
    {"managers.id": {"_eq": 5}}
  ]
}

Relationship filtering lets you query across related data using dot notation — filter events by account name, status properties, event type, or even which managers and salespeople are assigned:

GET /api/v2/events?filter={"account.name":{"_contains":"Acme"},"salespeople.id":{"_in":[5,12]}}

The full operator set: _eq, _neq, _gt, _gte, _lt, _lte, _in, _nin, _null, _nnull, _contains, _ncontains, _starts_with, _ends_with, _between, _nbetween, _empty, and _nempty.

Dynamic Filter Variables

Filters also support dynamic variables that resolve at query time, so you can build integrations and saved views that stay current without hardcoding dates or user IDs:

• $TODAY — resolves to today’s date, with optional offset: $TODAY(+7days), $TODAY(-1month)
• $NOW — resolves to the current timestamp, with offset and rounding: $NOW(-1hour), $NOW(/month) (start of current month)
• $CURRENT_USER — resolves to the authenticated user’s ID

For example, to get all events starting in the next 30 days:

GET /api/v2/events?filter={"start_date":{"_between":["$TODAY","$TODAY(+30days)"]}}

Or events managed by the current user:

GET /api/v2/events?filter={"managers.id":{"_eq":"$CURRENT_USER"}}

Aggregation for Dashboards and Reports

You can now request aggregate calculations — count, sum, average, min, max — alongside your filtered results. Aggregates are computed across all matching records, not just the current page.

Dashboard card in a single request:

GET /api/v2/events
  ?filter={"status.is_contracted":{"_eq":true},"start_date":{"_between":["2026-01-01","2026-03-31"]}}
  &aggregate[count]=*
  &aggregate[sum]=reported_price
  &aggregate[avg]=reported_profit
  &per_page=1

Response:

{
  "data": [...],
  "meta": {
    "total": 247,
    "aggregates": {
      "count": 247,
      "sum_reported_price": 1250000.00,
      "avg_reported_profit": 4800.50
    }
  }
}

Set per_page=1 to minimise the response payload when you only need the aggregate values. The aggregates always cover the full filtered result set regardless of pagination.

This works across all financial endpoints — events, costs, invoices, purchase orders, and credit notes — each with their own set of aggregatable fields.

Flexible Sorting

Sort by any allowed field, in any direction, with multi-field tie-breaking:

GET /api/v2/events?sort=-reported_price,name

The - prefix means descending. Combine with filters and aggregates for exactly the view you need.

Full-Text Search

A quick search parameter searches across each resource’s key text fields:

GET /api/v2/events?search=annual conference

Available Across All Endpoints

The new query system is available on every list endpoint in the v2 API:

• Events, Accounts, Contacts
• Costs, Cost Groups, Cost Tabs
• Invoices, Purchase Orders, Credit Notes
• Notes, Users, API Logs

Each endpoint documents its own filterable, sortable, and aggregatable fields directly in the API documentation.

Self-Documenting API

The API documentation has been significantly expanded. New guide pages cover Authentication, Filtering, Sorting, Pagination, and Aggregation with full operator references and examples. Every endpoint’s parameter descriptions automatically list the exact fields available for that resource — when we add new fields, the docs update themselves.

You can browse the docs at /docs/api on your own EventWorks instance, or explore them on our demo site.

Backwards Compatible

Existing API integrations continue to work unchanged. All legacy query parameters (like event_id, is_billable, group_id on cost endpoints, and notable_type/notable_id on notes) are still supported alongside the new filter syntax. You can migrate at your own pace.