Last updated

These docs are intended for a developer audience.

Search filters

This topic describes how to search for specific results using Rebilly collection APIs. This applies to API endpoints that return multiple resources, but not endpoints where a resource ID must be supplied.

Use the filter query parameter on a collection to define which records should be returned in the response. Fields and values in the filter are separated with :.

Fields are typed. As an example, you cannot search a boolean on a string field such as primaryAddress.lastName:true. This will result in an error.

This is an example of filtering on the Rebilly Transactions endpoint for transactions that are sales.

curl -G \
  -H 'REB-APIKEY: your-private-key' \
  --data-urlencode filter="type:sale"

Most values are not partially searched. They must be an exact case-insensitive match.

Compound filters

Filters are defined based on a specified field name and values separated by :. Multiple filters can be chained as well. These filters of field:value are separated by ;. These are joined together using AND logic.

The following is an example consisting of two filters, searching for transactions that are approved sales.

curl -G \
  -H 'REB-APIKEY: your-private-key' \
  --data-urlencode filter="type:sale;result:approved"

Field names

If a field name has sub-fields, in other words more than one "part", they are separated by a . in the field name.

For example a billing address, where the prefix is billingAddress but it has multiple properties such as firstName, lastName, etc.

billingAddress.lastName:SmithBilling address with a last name of "Smith".
customer.customFields.fieldName:trueA customers custom field with name fieldName.

Multiple values

Multiple values to search on a specified field are separated with , and use the logical disjunction of OR.

primaryAddress.firstName:JohnResults with firstName of John.
primaryAddress.firstName:John,BillResults with firstName of John OR Bill.

Boolean values

Boolean values are represented as true and false. They are written as a simple string filter but are interpreted as booleans.

isEddRequired:trueResults where a customer requires enhanced due diligence.

Empty values

Empty values are represented by using the keyword null as the value.

billingAddress.address2:nullResults where the address2 property in a billing address is empty or missing.
billingAddress.address2:!nullResults where address2 of the billing address is not empty.
description:Something,nullResults where a transaction description is either empty or contains the value Something.

Range filters

Range filters use .. to separate either end of a range. Ranges are always inclusive.

Ranges filters support integers, floats, and datetimes.

Ranges support integers, floats, and datetime. This also includes relative datetimes.

Dates and numeric filters cannot be mixed in a range filter.

Greater than or equals (gte) is represented as: 1...

Less than or equal (lte) is represented as: ..3.

revision:1..3With revision of 1, 2, or 3.
revision:2..Revision of 2 or higher.
revision:..2Revision of 2 or less.
createdTime:30 days ago..1 day agoCreated in the last 29 days.
createdTime:2024-01-20T00:00:00Z..2024-01-31T23:59:59ZCreated in January.


Our date-time based fields accept values formatted using RFC 3339.

Relative dates and times

Relative dates and times are accepted. Example: createdTime:7 days ago...

Relative dates and times are based from the moment the search occurs.

When using relative dates and times, now is defined as the moment the search occurs.

Dates and times on the edge of the time window can also be unpredictable. For example, 1 day ago means "one day ago from the current time this query is run."

For a list of acceptable entries and syntax, see Relative formats.

createdTime:2024-01-02T00:00:00Z..2024-01-02 at midnight or more recent.
createdTime:2 days ago..1 day agoCreated only two days ago.
createdTime:5 mins ago..1 min agoCreated only five minutes ago.

Negated filters

Negation is represented with a ! before the negated value: result:!approved.

To negate multiple fields, each value must be prefixed with !.

result:!approvedResults that are not approved.
result:!approved,!declinedResults that are not approved nor declined.

Values lists

Use values lists to compare against a list of data when setting conditions for rules or binds, or applying filters to data table segments. Commonly used lists contain values related to conditions that target specific properties such as: customers, transactions, or Bank Identification Numbers (BINs).

primaryAddress.firstName:@ListOfNamesUses a value list with an id of ListOfNames, those values are expanded and joined with OR.!@ExcludeCountriesReturn results that explicitly exclude from this list of countries.

Custom fields

Custom fields are searchable. They consist of a common prefix to the field, with the last part of the field name containing the name of the specific custom field to search.

For example, if you have a customer string-based custom field named "category". You might want to search all customers with category: "VIP".

curl -G \
  -H 'REB-APIKEY: your-private-key' \
  --data-urlencode filter="customFields.category:VIP"

Some collections can be searched on their specific resource of custom fields and on other related resources.

CollectionResourceField prefix
TransactionPayment instrumentpaymentCard.customFields
TransactionBump offerbumpOffer.selectedOffer.customFields

Monetary custom fields

Rebilly supports filtering on custom fields with type: monetary. Filter values are represented as integers or floats and optional ISO-4217 currency code. If the currency code is missing, then all currencies that match the associated amount are searched.

Do not include currency symbols.

See below for some examples.

customFields.SetupFee:9.99USD,14.99Filter on items with a custom field named SetupFee of 9.99 USD or 14.99 of any currency.
customFields.SetupFee:9.99..Filter on items with a custom field named SetupFee of 9.99 or higher in any currency.
customFields.SetupFee:10USD..20USDFilter on items with a custom field named SetupFee between (and including) 10 USD and 20 USD.
customFields.SetupFee:9.99CAD,9.99USD,5.99EURFilter on items with a custom field named SetupFee for values of 9.99 CAD, 9.99 USD, or 5.99 EUR.

Partial searches

Some fields support partial searching. All partial searches must consist of at least five characters at the beginning of the value. An asterisk is used to indicate a partial search after the preceding five characters.

curl -G \
  -H 'REB-APIKEY: your-private-key' \
  --data-urlencode filter="billingAddress.lastName:Smith*"