How to Filter Transactions by Metadata and Account in the v2 API

This article explains how to use complex filtering in the v2 transactions endpoint, including filtering by metadata existence and account names.

Filtering by Metadata Existence

To filter transactions where a specific metadata field does not exist, use the following syntax:

{ "$not": { "$exists": {"metadata": "field_name"} } }

For example, to filter transactions where the "bank_transaction_id" metadata field does not exist:

{ "$not": { "$exists": {"metadata": "bank_transaction_id"} } }

Complex Filtering Example

Here's an example of a more complex filter that combines multiple conditions:

{
  "$and": [
    { "$or": [
        {"$match" : { "account": "cass:1"}},
        {"$match": { "account": "cass:1:pending_withdrawal"}},
        {"$match": { "account": "cass:1:pending_return"}},
        {"$match": { "account": "cass:1:hold"}}
      ]
    },
    { "$not": { "$match": { "metadata[include_in_ext_cass_lookup]": "false" } } },
    { "$or": [
          { "$not": { "$exists": { "metadata": "bank_transaction_id" } } },
          { "$not": { "$exists": { "metadata": "gc_payment_id" } } }
        ]
    }
  ]
}

This filter does the following:

1. Includes transactions from specific 'cass' accounts

2. Excludes transactions where the metadata field "include_in_ext_cass_lookup" is set to "false"

3. Includes only transactions that are missing either the "bank_transaction_id" or "gc_payment_id" metadata fields

Best Practices for Complex Filters

• Each statement in $or/$and needs to be surrounded with curly braces {...}

• For better readability, consider filtering on accounts first, then apply metadata filtering

• Use proper nesting of $and and $or operators to achieve the desired logic

By following these guidelines, you can create powerful and precise filters for your transaction queries using the v2 API.