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 https://api-sandbox.rebilly.com/organizations/your-organization-id/transactions \ -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 https://api-sandbox.rebilly.com/organizations/your-organization-id/transactions \ -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.
| Query | Description |
|---|---|
billingAddress.lastName:Smith | Billing address with a last name of "Smith". |
customer.customFields.fieldName:true | A 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.
| Query | Description |
|---|---|
primaryAddress.firstName:John | Results with firstName of John. |
primaryAddress.firstName:John,Bill | Results 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.
| Query | Description |
|---|---|
isEddRequired:true | Results where a customer requires enhanced due diligence. |
Empty values
Empty values are represented by using the keyword null as the value.
| Query | Description |
|---|---|
billingAddress.address2:null | Results where the address2 property in a billing address is empty or missing. |
billingAddress.address2:!null | Results where address2 of the billing address is not empty. |
description:Something,null | Results 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.
| Query | Description |
|---|---|
revision:1..3 | With revision of 1, 2, or 3. |
revision:2.. | Revision of 2 or higher. |
revision:..2 | Revision of 2 or less. |
createdTime:30 days ago..1 day ago | Created in the last 29 days. |
createdTime:2024-01-20T00:00:00Z..2024-01-31T23:59:59Z | Created in January. |
Dates
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.
| Query | Description |
|---|---|
createdTime:2024-01-02T00:00:00Z.. | 2024-01-02 at midnight or more recent. |
createdTime:2 days ago..1 day ago | Created only two days ago. |
createdTime:5 mins ago..1 min ago | Created 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 !.
| Query | Description |
|---|---|
result:!approved | Results that are not approved. |
result:!approved,!declined | Results 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).
| Query | Description |
|---|---|
primaryAddress.firstName:@ListOfNames | Uses a value list with an id of ListOfNames, those values are expanded and joined with OR. |
primaryAddress.country:!@ExcludeCountries | Return 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 https://api-sandbox.rebilly.com/organizations/your-organization-id/customers \ -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.
| Collection | Resource | Field prefix |
|---|---|---|
| Customer | Customer | customFields |
| Order | Order | customFields |
| Order | Customer | customer.customFields |
| Transaction | Customer | customer.customFields |
| Transaction | Transaction | customFields |
| Transaction | Payment instrument | paymentCard.customFields |
| Transaction | Bump offer | bumpOffer.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.
| Query | Description |
|---|---|
customFields.SetupFee:9.99USD,14.99 | Filter 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..20USD | Filter on items with a custom field named SetupFee between (and including) 10 USD and 20 USD. |
customFields.SetupFee:9.99CAD,9.99USD,5.99EUR | Filter 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 https://api-sandbox.rebilly.com/organizations/your-organization-id/customers \ -H 'REB-APIKEY: your-private-key' \ --data-urlencode filter="billingAddress.lastName:Smith*"