Filtering and incremental sync

The filters parameter

Many list endpoints accept a filters parameter.
Its value is a URL-encoded JSON array of filter objects, and all filters must match (AND).

Each filter object has these keys:

Key	Meaning
`type`	`string` (also for numbers and IDs), `date` or `boolean`
`column`	A column the endpoint allows, or a custom field of the endpoint's record type as `field_<id>`
`operator`	One of the operators of that type; `boolean` filters have none
`value`	The value; see the operators below

String operators: contains, not_contains, equals, not_equals, greater_than, less_than, is_null, is_not_null, in_list, not_in_list.
in_list and not_in_list take an array or a comma-separated string.

Date operators: between ("YYYY-MM-DD,YYYY-MM-DD"), specific_date, before, after, specific_year, today, tomorrow, yesterday, this_week, this_week_end, next_week, next_two_weeks, next_week_end, this_month, last_3_months, next_3_months, this_quarter, last_quarter, next_quarter, this_year, last_year, next_year, past_year, coming_year.
Date filters match whole days in the time zone your API user works in (see Dates, time zones and money); before and after include the given day.

Boolean filters: send 1 or 0, for example {"type": "boolean", "column": "reservation_from_website", "value": 1}.
The string "false" counts as true.

Unknown filters are ignored

A filter whose column is not allowed by the endpoint, whose type does not match the column, or whose operator does not belong to its type is dropped without an error, and you get unfiltered results.
Custom field columns (field_<id>) are the exception: any custom field is accepted, and one that belongs to another record type makes the request fail instead of being ignored.
Test every new filter and check that the result count changes.
If filters is not valid JSON, the API returns HTTP 400.

Each list endpoint has its own allowed columns, listed under its filters parameter where the endpoint reference documents one.
Some list endpoints, such as vehicles and locations, accept filters that are not documented yet; ask HQ Support for their columns.

Incremental sync with updated_since

Instead of reading everything again, ask only for the records that changed.
These list endpoints accept updated_since and return the records updated at or after that moment:

GET /car-rental/reservations (v1)

GET /car-rental/rates (v1 and v2)

GET /car-rental/rate-types

GET /car-rental/seasons

GET /fleets/vehicles

GET /fleets/vehicle-classes

GET /contacts/categories and GET /contacts/categories/{category_id}/contacts

GET /invoices/invoices/e-invoices/{format}

updated_since is always in UTC, formatted YYYY-MM-DD HH:mm:ss, whatever time zone the responses use.

A reliable sync loop:

Record the current UTC time before you start.

Read every page, with the same parameters on each, and updated_since set to the start time of your previous run, minus a few minutes of overlap.

Upsert the records by id; the overlap can return a record twice.

Save the time from step 1 for the next run.

updated_since never returns deleted records.
Some lists also leave out inactive records: vehicle classes (including those of inactive branches), rate types and seasons never return inactive ones, and vehicles leave out unavailable, sold and on-sale ones, and those whose class or branch is inactive, unless you send show_inactive=1.
A record that is deactivated simply stops appearing, and no Deleted webhook is sent for it.
To detect deletions, use Deleted webhooks (see Webhooks) or regularly compare the full list of IDs; to detect deactivations, compare the full list of IDs.

The filters parameter#

Unknown filters are ignored#

Incremental sync with updated_since#

The filters parameter

Unknown filters are ignored

Incremental sync with updated_since