Many of our endpoints provide common filters which allow you to refine your search results, allowing you to only retrieve the information you are looking for. These filters fall into three main categories:

1. Filtering results by time (e.g. transaction times, card termination dates)
2. Filtering results by numeric value (e.g. transaction amounts, transfer amounts)
3. Removing irrelevant fields from the output (filter keys)

Time Filtering

The common time filters present in our endpoints allow you to construct queries using combinations of before, before_or_on, after, and after_or_on.

Combining Filters

If you specify two or more of these for a single parameter, their conjunction will be taken. For example, suppose you wanted to filter results where version_time is between 2023-01-01 and 2023-02-15inclusive (i.e. the range [2023-01-01, 2023-02-15]. You can do this by combining after_or_on and before_or_on(i.e. version_time_after_or_on = 2023-01-01 and version_time_before_or_on = 2023-04-15) to generate a query equivalent to 2023-01-01 <= version_time AND version_time <= 2023-04-15

Disjoint Time Ranges

In the event where you wanted to retrieve results in disjoint time periods (e.g. two different days), multiple queries are required (one for each disjoint time period). If you specify two disjoint time periods in a single request, an empty search result will occur since there will be no matches.

For example, if you wanted all values where version_time is before 2023-03-01 and all values after 2023-03-04, if both are specified at once, you'll have constructed a query equivalent to the following: version_time <= 2023-03-01 AND version_time >= 2023-03-04which will never have matches.

Numeric Value Filtering

Similar to the date filters, the common time filters present in our endpoints allow you to construct queries using combinations of less_than, less_than_equal_to, greater_than, and greater_than_equal_to.

Combining Filters

Specifying a combination of these filters for a single parameter will result in their conjunction in the final query. For example, suppose you wanted to filter results where amount is between 10 and 20 not including 20 (i.e the range [10, 20)) you can combine greater_than_equal_to and less_than (i.e. amount_greater_than_equal_to = 10 and amount_less_than = 20) to generate a query equivalent to the following: amount >= 10 AND amount < 20

Disjoint Value Ranges

In the event where you would like to retrieve results in disjoint number ranges, multiple queries are required (one for each disjoint number range). If you specify two disjoint ranges in a single request, an empty search result will occur since there will be no matches.

Filter Keys

If you would like to remove output fields irrelevant to your application, you can do so by using the filter_keysparameter which most endpoints provide. This parameter allows you to specify exactly which fields you would like present in the output results.

For example, suppose that an endpoint generally outputs the following in response to a valid request:

{
  'first_name': 'John',
  'last_name': 'Smith',
  'address': {
    'address_line_1': 'Unit 12',
    'address_line_2': '10 Jane Street',
    'city': 'Miami',
    'state': 'FL',
    'zip_code': '11010'
  },
  'phone_number': '0123456789'
}

If we only need to retrieve the first_name and city fields, we can provide the following filter_keys parameter:

filter_keys=first_name,address.city

which will result in the output changing to

{
  'first_name': 'John',
  'address': {
    'city': 'Miami',
  }
}