Search filters

This topic describes how to search for specific results using Rebilly collection APIs. This information applies to API endpoints that return multiple resources. It does not apply to endpoints that require a resource ID.

Use the filter query parameter on a collection to select the records that are returned in the response. Fields and values in the filter are separated with :.

Fields are typed. Use a value that matches the type of a field. For example, a boolean value on a string field, such as primaryAddress.lastName:true, does not match any results.

The following example uses the filter query parameter to retrieve sales transactions from the Transactions endpoint.

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 must be an exact case-insensitive match. Some fields support partial searches.

A filter consists of a field name and values separated by :. To chain multiple filters, separate each field:value pair with ;. The filters are joined with AND logic.

The following example uses two filters to search for approved sales transactions.

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 that contain subfields use a . to separate each part.

For example, billing address fields use the billingAddress prefix with properties such as firstName and lastName. The complete field name for firstName is billingAddress.firstName.

Separate multiple values for one field with ,. The values are joined with OR logic.

This section lists all reserved characters and how to use them.

• : separates a field from its value. Only the first : in a filter is a separator. A : in a value does not require a backslash.
• ; separates filters.
• , separates values.
• To include a ; or a , in a value, add a backslash before it.
• A backslash before :, ;, or , makes the character part of the value, and the filter drops the backslash. Before any other character, the backslash stays in the value. For information on * and ?, see Partial searches.
• A value that contains .. becomes a range. A backslash does not affect range parsing.

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

Empty values use the keyword null.

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

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

A range filter that mixes dates and numeric values is not valid.

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

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

Date-time fields accept values formatted using RFC 3339.

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

In relative dates and times, now is the moment the search occurs.

Dates and times on the edge of the time window can 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.

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

To negate multiple values, prefix each value with !.

Use value lists to compare a value against a list of data. Value lists apply to conditions for rules or binds, and to filters on data table segments. Common lists contain values for conditions that target specific properties. Examples include customers, transactions, and Bank Identification Numbers (BINs).

For information on how to manage lists using the Rebilly API, see Lists. Code examples are provided for all API endpoints.

Custom fields are searchable. Each custom field name starts with a common prefix. The last part of the name is the custom field to search.

For example, a customer has a string-based custom field named "category". To search all customers with category: "VIP", use the following request.

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 support a search on their own custom fields, and on the custom fields of related resources.

Use filters on custom fields with type: monetary. A filter value is an integer or a float. An ISO-4217 currency code is optional. If there is no currency code, the search covers every currency with that amount.

See the following examples.

Some fields support partial searches. Partial matching applies when a filter has one value. If a filter has multiple values, each value must be an exact match.

Contact name and email fields, company fields, and string custom fields match by prefix. A value matches every result that starts with it. In a prefix field, an asterisk is part of the value to match.

The following example returns customers with a last name that starts with "Smi", such as Smith or Smithers.

curl -G https://api-sandbox.rebilly.com/organizations/your-organization-id/customers \
  -H 'REB-APIKEY: your-private-key' \
  --data-urlencode filter="primaryAddress.lastName:Smi"

Resource IDs, and the url and route fields of log resources, support wildcards. Use * to match any number of characters, and ? to match one character. To match a literal * or ?, add a backslash before it. The first five characters of a value must be literal. The filter ignores wildcards in the first five character positions.

The following example returns transactions with an ID that starts with txn_0YV.

curl -G https://api-sandbox.rebilly.com/organizations/your-organization-id/transactions \
  -H 'REB-APIKEY: your-private-key' \
  --data-urlencode filter="id:txn_0YV*"