API filters now do what the docs say

API

We audited every filter on the v2 API against the code behind it. Several documented filters were quietly doing nothing: a value the server didn’t recognise was ignored, so you got your whole collection back with no error to say the filter hadn’t applied. This update fixes the filters and the docs together, so what’s on the page is what the server does.

One way to write a boolean

Every filter marked boolean now takes true or false. Before, it depended on the endpoint: some wanted true, some 1, and some a word like unarchived. Tickets archived and photo, and events archived_at, were documented as true/false but didn’t accept it. On events the canonical name is now filter[archived].

The older spellings keep working, so nothing you already send breaks. Any other value is ignored, as before. See Filtering & sorting.

New ticket filters

  • filter[sent]: tickets that have, or haven’t, been emailed to the attendee.
  • filter[expired]: tickets past their expires_at, or still valid.
  • filter[deleted]: deleted tickets only. If you mirror tickets on an updated_at cursor, this is how you find out what was removed.

filter[status] now documents the statuses a ticket actually has: confirmed, checked_in, checked_out, voided, transferred and pending. You can pass several, comma separated. Emailed and expired were never statuses, which is why status=sent and status=expired always returned nothing; use the new filters above for those.

Tickets also return sent_at, the time the ticket was last emailed. It carries the same value as dispatched_at, which stays for existing integrations; use sent_at going forward.

Filters that work everywhere

  • filter[created_at][from] and [to] now work on every endpoint that lists filters. A to with no time covers that whole day.
  • filter[id] now works on /events and /recurring_events. It was being ignored on both.
  • /events accepts filter[published].
  • filter[deleted] replaces filter[permanence] on tickets, events and arrivals. If you poll arrivals for deletions, switch to filter[deleted]=true; see Removed arrivals.

Voiding a ticket that can’t be voided

PATCH /tickets/{id}/void now returns 422 with type: invalid_state when the ticket is already voided, transferred or pending, instead of a silent 200. It also takes notify, to choose whether the ticket holder is emailed, and an optional reason, which is kept as a note on the ticket. See Void ticket.

Fixes

  • Events search with filter[status]=tomorrow always returned nothing. It now returns tomorrow’s events.
  • A malformed date in a range filter is now ignored instead of causing a server error.
  • On searches, ticket filter[status] and order filter[state] now accept comma separated lists, the same as without a search term.

Check your integration

If you were already sending one of these filters, you may now get fewer results than before, because the filter is finally being applied:

  • filter[archived]=true or false on tickets, or filter[archived_at]=true or false on events.
  • filter[photo]=true or false on tickets.
  • filter[id] on /events or /recurring_events.
  • filter[created_at] on any endpoint.

If a void call retries on failure, treat 422 invalid_state as final rather than retrying.

Jeff Blake
← Back to release notes