#

Filters

You can filter the results for all GET multiple objects endpoints via where query parameter. This makes it easy to retrieve specific information, like any accounts assigned to a particular entity, or all transactions completed after a given date.

For example, to return all transaction lines for a certain account you can use the following query:

GET /transactions/lines?where={account_id:"some_random_id1"}

As you noticed in above example, we accept where params as JSON, however you don't have to wrap it in top-level brackets and can do simpler queries like this.

GET /transactions/lines?where=account_id:"some_random_id1"

Filtering works the same way on all properties of all objects and below are the available comparators for different types:

#

Combining Filters

You can filter by more than one property at once, e.g:

GET /transactions?
where={
  account_id: "some_random_id1",
  entity_id: "some_other_id"
}

By default all properties at the same level are part of the same AND logical group.

But you can combine filters into more complex ones with AND and OR operators.

GET /transactions?
where={
  OR: [
    {
      AND: [
        { external_id: { contains: "123_" } },
        { external_id: { contains: "_xyz" } }
      ]
    },
    {
      entity_id: "some_random_id2",
      route_id: "some_random_id3",
    }
  ]
}

#

Filtering on Related Fields

It is also possible to filter based on arrays of related fields.

For example, to return all transactions that have a line of 500.00 or more you can use the following query.

GET /transactions?where={lines:{some:{amount:{gte: 500}}}}

These filters can be nested and combined just like the other filters.

For example, to return all accounts that have a balance less than 0 and are active we could use the following query.

GET /accounts?where={status:'active', balances:{some:{amount:{lt: 0}}}}

Filter Reference

• eq: equals to X.
• neq: does not equal X.
• in: matches at least one item in the array X.
• not_in: does not match any items in the array X.
• gt: greater than X.
• gte: greater than or equal to X.
• lt: less than X.
• lte: less than or equal to X.
• like: contains the string X.
• some: some element in the array matches the filter (at least one). - none: no elements in the array match the filter.
• every: all elements in the array match the filter.
• contains: A json field contains the provided filter (see below for explanation and examples).
• not_contains: the opposite of contains (see below for explanation and examples).
• exists: The provided filter is a json path and the json field contains that path (see below for explanation and examples).
• not_exists: the opposite of exists.

#

Json Filters

There are two unique filters to json fields, contains/not_contains and exists/not_exists. The following JSON is used as an example in the explanations below

Sample JSON
{
  "id" : "a",
  "variables": {
    "metadata": {
      "created_at": "date"
    }
  }
  "data": [
    {
      "index": 0
      "name": "First array value",
      "parameters": {
        "data": "some data",
        "nested_data": {
          "more_data": "data"
        }
      },
      "archived_at": null,
    }
  ]
}

Contains and not_contains are used to filter on the values of a json field. They test that the json field we are filtering on either has or does not have the provided filter inside of it. For example:

To test if it contains an id with value "a" we can use the filter
{ contains: { "id": "a" } } would return true on our sample JSON
 
More examples:
{ contains: { "archived_at": {} } } would return false on our sample JSON
{ not_contains: { "id": {} } } would return false on our sample JSON because even though 'id' exists in the JSON, it is a string, not an object.
{ contains: { "variables": {} } } would return true on our sample JSON.

Exists and not_exists are used to filter on the existence of fields in a json. For example:

To test if the json has an id field we can use
{ exists: "id" } this would return true on our sample JSON
{ not_exists: "id" } would return false on our sample JSON