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:
Property type | Available comparators |
---|---|
String | eq , neq , in , not_in , gt , lt , gte , lte , like |
Number | eq , neq , in , not_in , gt , lt , gte , lte |
Enum | eq , neq , in , not_in |
Date | eq , neq , in , not_in , gt , lt , gte , lte |
Array | some , none , every |
Json (object, dictionary, map) | contains , not_contains , exists , not_exists , eq , neq |
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