API Filtering Conventions

Our API supports a flexible filtering system that allows you to narrow down results when retrieving collections of resources (e.g., lists of accounts, members, or other entities). This guide explains the general pattern for using filters in your requests.

1. Basic Usage

When making a request, you can include one or more filter parameters in the query string. Each filter parameter is structured as:

?filter[field_name__operator]=value

• field_name: The field (or attribute) of the resource you want to filter by.
• __operator: An optional suffix that defines the type of comparison (e.g., __match, __gte, __lte).
• value: The desired value or range to match.

Operators are active on some endpoint only API Reference should be consulted to know which operators are available for each endpoint.

Example

GET /iam/accounts?filter[email__match]=john

This request returns all accounts with an email address containing the substring john.

2. Common Operators

Below are some common operators you can use in your filter parameters:

1. Exact Match:
   • Pattern: filter[field_name]=value
   • Purpose: Returns resources whose field_name exactly matches the specified value.
2. IN Operator:
   • Pattern: filter[field_name__in]=value1,value2,value3
   • Purpose: Returns resources whose field_name matches any of the listed values.
   • Example: ?filter[id__in]=1,2,3
3. Greater Than or Equal (__gte):
   • Pattern: filter[field_name__gte]=value
   • Purpose: Returns resources where field_name is greater than or equal to value.
   • Example: ?filter[created_at__gte]=2023-01-01
4. Less Than or Equal (__lte):
   • Pattern: filter[field_name__lte]=value
   • Purpose: Returns resources where field_name is less than or equal to value.
   • Example: ?filter[expires_at__lte]=2023-12-31
5. Partial Match (__match):
   • Pattern: filter[field_name__match]=value
   • Purpose: Returns resources where field_name contains the substring value.
   • Example: ?filter[email__match]=@example.com

3. Combining Multiple Filters

You can include multiple filter parameters in the same request to refine your search further. For instance:

GET /iam/accounts?filter[enabled]=true&filter[created_at__gte]=2023-01-01&filter[email__match]=john

This query would return:

1. Accounts that are enabled.
2. Were created on or after 2023-01-01.
3. Have an email containing “john”

Note: The match filter is case-insensitive

4. Handling Arrays and Lists

When using the __in operator, separate multiple values by commas:

GET /iam/accounts?filter[id__in]=1,2,3

The API interprets the comma-separated string as a list of values. In this example, it matches id equals 1 OR 2 OR 3.

5. Valid Fields and Filters

Not all fields in a resource may be available for filtering. Consult each resource’s documentation or schema reference to see which fields you can filter on. If you attempt to filter on a field or use an operator that isn’t supported, the API will ignore the filter.

6. Putting It All Together

• Use filter[...] parameters in the query string.
• Add __operator to refine how the value is matched (e.g., __match for partial matches, __gte for ranges).
• Combine multiple filters with & in the query string to narrow down results.
• Use commas for list values with __in.

By following these conventions, you can create highly targeted requests to get exactly the data you need from our API.

Example Final Request

GET /iam/accounts?filter[enabled]=true&filter[id__in]=42,100&filter[created_at__lte]=2024-01-01

• Returns enabled accounts
• Whose id is in the set {42, 100}
• That were created on or before January 1, 2024.

Questions?

If you have questions or need further assistance, consult your account manager or our API Reference for more detailed examples.