Search

Many of the Flowbrite resources support search queries, allowing you to filter results based on your own criteria. This guide will help you understand how to use search queries effectively.

Queries

A search query is made by combining two key objects, conditions and condition groups.

Conditions

A condition is made up of the following:

Name
field
Type
string
Type
Description
The field to filter on, e.g. DisplayName, Address.CountryCode. Please check the resource you are querying for available fields.
Name
operator
Type
string
Type
Description
The operator to use for filtering, e.g. Contains, Equals. Different field types support different operators, please check the table below for details.
Show enum values
Name
value
Type
string
Type
Description
The value to filter by, e.g. "Travel", "ZA".
This is always a quoted string, regardless of the field type.

Condition Example

{
  "query": {
    "field": "DisplayName",
    "operator": "Contains",
    "value": "Travel"
  }
}

Field Types and Condition Operators

The following table shows the available operators for each field type. The GET Operator columns indicates how this operator can be used in a GET request.

Enum	GET Operator	Id	String	Number	Boolean	Date	Enum
Equals	`==`	✅	✅	✅	✅	✅	✅
DoesNotEqual	`!=`	❌	✅	✅	✅	✅	✅
GreaterThan	`>`	❌	❌	✅	❌	✅	❌
GreaterThanOrEqual	`>=`	❌	❌	✅	❌	✅	❌
LessThan	`<`	❌	❌	✅	❌	✅	❌
LessThanOrEqual	`<=`	❌	❌	✅	❌	✅	❌
Contains	`~`	❌	✅	❌	❌	❌	❌
DoesNotContain	`!~`	❌	✅	❌	❌	❌	❌
StartsWith	`^=`	❌	✅	❌	❌	❌	❌
EndsWith	`$=`	❌	✅	❌	❌	❌	❌
Before	`<d`	❌	❌	❌	❌	✅	❌
OnOrBefore	`<=d`	❌	❌	❌	❌	✅	❌
After	`>d`	❌	❌	❌	❌	✅	❌
OnOrAfter	`>=d`	❌	❌	❌	❌	✅	❌

Condition Groups

A condition group is a collection of conditions (or condition groups to allow more complex nested queries) that are combined using a logical group operator.

Name
groupOperator
Type
string
Type
Description
The operator to use for combining conditions in the group.
Show enum values
Name
conditions
Type
object[]
Type
Description
An array of conditions or condition groups that are part of this group.

Condition Group Example

{
  "query": {
    "groupOperator": "AND",
    "conditions": [
      {
        "field": "DisplayName",
        "operator": "Contains",
        "value": "Travel"
      },
      {
        "groupOperator": "OR",
        "conditions": [
          {
            "field": "Address.CountryCode",
            "operator": "Equals",
            "value": "ZA"
          },
          {
            "field": "Address.CountryCode",
            "operator": "Equals",
            "value": "NA"
          }
        ]
      }
    ]
  }
}

Pagination

Pagination is handled using the offset and limit parameters.

Name
offset
Type
integer
Type
Description
The number of items to skip before starting to collect the result set.
Name
limit
Type
integer
Type
Description
The maximum number of items to return.

Pagination Example

{
  "offset": 0,
  "limit": 10
}

Sorting

Sorting is specified using the sortBy parameter.

Name
sortBy
Type
string[]
For GET collection endpoints
Type
Description
One or more sort clauses in fieldName:ASC|DESC format, e.g. DisplayName:DESC. Repeat the sortBy query string parameter to apply multiple sorts.
Name
sortBy
Type
object[]
For POST /search endpoints
Type
Description
One or more sort clauses with field and order properties.
Show sort clause properties

POST /search Example

{
  "sortBy": [
    {
      "field": "DisplayName",
      "order": "DESC"
    }
  ]
}

GET Query String Example

sortBy=DisplayName:DESC

Putting it Together

Below is an example of a complete search query that combines all the elements we've discussed.

The query object can be either a single condition or a condition group.

Request

POST

/v1/clients/{clientId}/beneficiaries/search

{
  "query": {
    "groupOperator": "AND",
    "conditions": [
      {
        "field": "DisplayName",
        "operator": "Contains",
        "value": "Travel"
      },
      {
        "groupOperator": "OR",
        "conditions": [
          {
            "field": "Address.CountryCode",
            "operator": "Equals",
            "value": "ZA"
          },
          {
            "field": "Address.CountryCode",
            "operator": "Equals",
            "value": "NA"
          }
        ]
      }
    ]
  },
  "offset": 0,
  "limit": 10,
  "sortBy": [
    {
      "field": "DisplayName",
      "order": "DESC"
    }
  ]
}

Responses

Every search query returns a data array containing the results that match the query, along with a meta object that provides additional information to assist with understanding the results.

Name
data
Type
object[]
Type
Description
An array of objects that match the search query.
Name
meta
Type
object
Type
Description
Metadata about the search results.
Show meta properties

Search Response Example

{
  "data": [
    ...
  ],
      "meta": {
        "query": "AND(DisplayName~\"Travel\",OR(Address.CountryCode==\"ZA\",Address.CountryCode==\"NA\"))",
        "sortBy": ["DisplayName:DESC"],
        "offset": 0,
        "limit": 10,
        "count": 2,
        "totalCount": 2,
        "timestamp": "2025-06-16T10:48:04.5512525Z"
    }
}

If you prefer to use a GET request instead of a POST request for search queries (as is widely done in this documentation), you can do so by passing the arguments as query string parameters to the resource collection endpoint.

The query string parameters are as follows:

q: The URL encoded search query, which can be a single condition or a condition group (see syntax below)
sortBy: One or more sort clauses in fieldName:ASC|DESC format.
offset: The number of items to skip before starting to collect the result set.
limit: The maximum number of items to return.

Syntax

The syntax is hopefully intuitive, using a simple query language that allows you to express conditions and groups of conditions as comma-separated values, and nested-values.

Conditions are expressed as field operator value, e.g. DisplayName~"Travel".
Condition groups are expressed as groupOperator(condition1, condition2, conditionGroup1, ...), e.g. AND(condition1, condition2).

You should use the GET Operator syntax for the condition operators (e.g. ~, ==, != etc).

Example

AND(
  DisplayName~"Travel",
  OR(
    Address.CountryCode=="ZA",
    Address.CountryCode=="NA"
  )
)

Example Request

GET

/v1/clients/{clientId}/beneficiaries

  curl -G https://api.flowbrite.io/v1/clients/{clientId}/beneficiaries \
  -H "X-API-KEY: {api_key}" \
  -d 'q=AND(DisplayName~"Travel",OR(Address.CountryCode=="ZA",Address.CountryCode=="NA"))' \
  -d "sortBy=DisplayName:DESC" \
  -d "offset=0" \
  -d "limit=10"