Filtering the list of contacts retrieved via the API.

Jaroslav Bouška Jaroslav Bouška
5. September 2025

By dispatching a request to the API endpoint GET /v1/contacts, you get a list of all contacts, including properties like first name, last name, and email. Using a filter you can further refine the resulting list and work with individual contacts more efficiently.

Using filters, you can list, for example, contacts who registered in your database after January 31, 2020, or whose shoe size is greater than 45. Below you’ll find instructions on how to do it.

Previous API versions didn’t allow filtering contacts by data in custom fields. The new contacts filter does, and you can use various operators. The feature is backward-compatible, so your old requests will keep working and return the same results as before.

You can use 9 operators for filtering:

  • eq – is equal (exact match)
  • !eq – is not equal (not equal, differs)
  • gt – greater than (greater than)
  • lt – less than (less than)
  • ct – contains
  • set – is set (configured)
  • !set – is not set (not set)
  • true – the value of the boolean attribute is true
  • false – the boolean attribute value is false.

New operators can be used on custom fields of type string (text), number (numbers), boolean (yes / no), date (date) and datetime (date and time). Only some of the defined operators are available for each data type:

  • string – eq, !eq, ct, set, !set
  • number – eq, !eq, gt, lt, set, !set
  • boolean – set, !set, true, false
  • date – eq, !eq, gt, lt, set, !set
  • datetime – eq, !eq, gt, lt, set, !set

Let’s go straight to an example where we have contacts in the system with a data structure similar to this:

Contact {
  string firstName,
  string lastName,
  string email,
  lastOrderDate date,
  ordersCount int,
  isEnabled bool
}

FirstName, lastName and email are system columns, lastorderdate, orderscount and isenabled are custom fields. We want to retrieve contacts who have an email on the list, whose last order date is before 9/1/2023, have more than 3 orders, and are enabled. The resulting request URI will look like this:

https://api.boldem.cz/v1/contacts?filter=email~ct~seznam.cz|lastorderdate~lt~2023-09-01|orderscount~gt~3|isenabled~true

Filter items are separated by the vertical bar |. Each filter item can consist of 2 to 3 parts separated by a tilde ~. If it has three parts, the first part is the custom field identifier, the second is the operator, and the third is the filter value. If it has two parts, the first part is the custom field identifier and the second is either an operator that doesn’t require a filter value (set, !set, etc.) or a value. In this case, eq is used as the operator.

Operator-based filters can, of course, be combined with the sort and include parameters, for example by calling:

https://api.boldem.cz/v1/contacts?filter=email~ct~seznam.cz|lastorderdate~lt~2023-09-01|orderscount~gt~3|isenabled~true&sort=contactId~desc&include=customColumns

We will retrieve the contacts defined above, sorted from newest to oldest, and the response will include each contact’s custom fields.

Full API documentation is available at https://api.boldem.cz/

Související články