# 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](/catalog/all/transactions/gettransactioncollection) for transactions that are sales.


```curl
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.](#partial-searches)
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
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.](https://www.rfc-editor.org/rfc/rfc3339)

### 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](https://www.php.net/manual/en/datetime.formats.php#datetime.formats.relative).

| 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](/docs/dev-docs/api/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
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](/docs/dev-docs/customers) | [Customer](/docs/dev-docs/customers) | `customFields` |
| [Order](/docs/dev-docs/orders) | [Order](/docs/dev-docs/orders) | `customFields` |
| [Order](/docs/dev-docs/orders) | [Customer](/docs/dev-docs/customers) | `customer.customFields` |
| [Transaction](/docs/dev-docs/transactions) | [Customer](/docs/dev-docs/customers) | `customer.customFields` |
| [Transaction](/docs/dev-docs/transactions) | [Transaction](/docs/dev-docs/transactions) | `customFields` |
| [Transaction](/docs/dev-docs/transactions) | [Payment instrument](/docs/dev-docs/payment-instruments) | `paymentCard.customFields` |
| [Transaction](/docs/dev-docs/transactions) | 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
curl -G https://api-sandbox.rebilly.com/organizations/your-organization-id/customers \
  -H 'REB-APIKEY: your-private-key' \
  --data-urlencode filter="billingAddress.lastName:Smith*"
```