Filters

The API provides methods for listing resources. For example, you can list apps, list users, and list contracts. Where filters are supported, these API list methods share a common structure for filters.

Why use Filters?

By combining multiple filters (in an AND relation) and utilizing the different operations, you can execute a wide variety of calls to help you achieve the exact response you're looking for.

For simpler use cases, use basic key=value filters.

While both types of filters can be used in conjunction, we recommend using only one.

This guide explains all available filter operations in the Torii Public API, which operations work with which field types, and provides practical examples.

Filter Structure

All filters follow this structure:

{
  "key": "fieldName",  // or { "value": "fieldName" }
  "op": "operationName",  // or { "value": "operationName" }
  "value": "filterValue"  // type depends on the operation
}

You can pass filters in one of two formats:

1. Array of Filters (AND logic)

When you pass an array of filters, all filters are combined using AND.

This means an item must match all filters in order to be returned.

Example

The following query returns apps whose name contains "test" and whose category equals "security":

/apps?filters=[
  {
    "key":"name",
    "op":"contains",
    "value":"test"
  },
  {
    "key":"category",
    "op":"equals",
    "value":"security"
  }
]

2. Array of Filter Groups (OR logic)

You can also pass an array of Filter Groups.

In this format:

Each filter group contains:
- An id field (any unique string)
- A filters array
Filters inside a group are combined with AND
Filter groups are combined with OR

This means an item can match any filter group in order to be returned.

Structure

[
  {
    "id": "group-1",
    "filters": [
      {
        "key": "fieldName",
        "op": "operationName",
        "value": "filterValue"
      }
    ]
  }
]

Example

The following query returns apps that match either of these conditions:

Name contains "test" AND category equals "security"
Name contains "prod" AND category equals "finance"

/apps?filters=[
  {
    "id":"group-1",
    "filters":[
      {
        "key":"name",
        "op":"contains",
        "value":"test"
      },
      {
        "key":"category",
        "op":"equals",
        "value":"security"
      }
    ]
  },
  {
    "id":"group-2",
    "filters":[
      {
        "key":"name",
        "op":"contains",
        "value":"prod"
      },
      {
        "key":"category",
        "op":"equals",
        "value":"finance"
      }
    ]
  }
]

Available Operations by Field Type

1. Text Fields (singleLine, multiLine, email, cardNumber)

Supported Operations:

Operation	Description	Value Type	Example
`equals`	Exact match (case-sensitive)	String	`"value": "John"`
`notEquals`	Does not match exactly	String	`"value": "John"`
`contains`	Substring match (case-insensitive)	String	`"value": "john"`
`notContains`	Does not contain substring	String	`"value": "spam"`
`isSet`	Field has any value	N/A	No value needed
`isNotSet`	Field is empty/null	N/A	No value needed

Examples:

[
  {
    "key": "email",
    "op": "equals",
    "value": "[email protected]"
  },
  {
    "key": "firstName",
    "op": "contains",
    "value": "John"
  },
  {
    "key": "description",
    "op": "isSet"
  }
]

2. Numeric Fields (number, currency)

Supported Operations:

Operation	Description	Value Type	Example
`equals`	Exact value	Number	`"value": 1000`
`notEquals`	Not equal to value	Number	`"value": 1000`
`gt`	Greater than	Number	`"value": 500`
`gte`	Greater than or equal	Number	`"value": 500`
`lt`	Less than	Number	`"value": 5000`
`lte`	Less than or equal	Number	`"value": 5000`
`between`	Within a range	Array of 2 numbers	`"value": [100, 1000]`
`isSet`	Field has any value	N/A	No value needed
`isNotSet`	Field is empty/null	N/A	No value needed

Notes:

For currency fields, values are in the base currency unit (e.g., cents for USD)
between requires exactly 2 values: [min, max]

Examples:

[
  {
    "key": "amount",
    "op": "gte",
    "value": 50000
  },
  {
    "key": "cost",
    "op": "between",
    "value": [10000, 100000]
  },
  {
    "key": "users",
    "op": "gt",
    "value": 100
  }
]

3. Date Fields (datePicker)

Supported Operations:

Operation	Description	Value Type	Example
`equals`	Exact date	ISO 8601 date string	`"value": "2024-12-31"`
`notEquals`	Not on this date	ISO 8601 date string	`"value": "2024-12-31"`
`dayAfter`	After this date (exclusive)	ISO 8601 date string	`"value": "2024-01-01"`
`dayOnOrAfter`	On or after this date	ISO 8601 date string	`"value": "2024-01-01"`
`dayBefore`	Before this date (exclusive)	ISO 8601 date string	`"value": "2024-12-31"`
`dayOnOrBefore`	On or before this date	ISO 8601 date string	`"value": "2024-12-31"`
`relativeDateToday`	Exactly today	N/A	No value needed
`relativeDateOn`	On a specific day name	String: "Monday", "Tuesday", etc.	`"value": "Monday"`
`relativeDateLess`	In the last N days	Number	`"value": 30`
`relativeDateMore`	More than N days ago	Number	`"value": 30`
`isSet`	Field has any date	N/A	No value needed
`isNotSet`	Field is empty/null	N/A	No value needed

Examples:

[
  {
    "key": "startDate",
    "op": "dayOnOrAfter",
    "value": "2024-01-01"
  },
  {
    "key": "endDate",
    "op": "dayBefore",
    "value": "2024-12-31"
  },
  {
    "key": "createdDate",
    "op": "relativeDateLess",
    "value": 90
  },
  {
    "key": "renewalDate",
    "op": "relativeDateToday"
  }
]

4. Dropdown/Select Fields (dropdown, dropdownMulti)

Supported Operations:

Operation	Description	Value Type	Example
`equals`	Exact match	String	`"value": "active"`
`notEquals`	Does not equal	String	`"value": "inactive"`
`isExactly`	Exact match (alias for equals)	String	`"value": "approved"`
`anyOf`	Matches any value in list	Array of strings	`"value": ["active", "pending"]`
`noneOf`	Matches none of the values	Array of strings	`"value": ["archived", "deleted"]`
`allOf`	Contains all values (for multi-select)	Array of strings	`"value": ["tag1", "tag2"]`
`isSet`	Field has any value	N/A	No value needed
`isNotSet`	Field is empty/null	N/A	No value needed

Examples:

[
  {
    "key": "status",
    "op": "equals",
    "value": "active"
  },
  {
    "key": "lifecycleStatus",
    "op": "anyOf",
    "value": ["active", "offboarding"]
  },
  {
    "key": "category",
    "op": "noneOf",
    "value": ["deprecated", "archived"]
  }
]

5. User Fields (usersDropdown, usersDropdownMulti)

Supported Operations:

Operation	Description	Value Type	Example
`equals`	Assigned to specific user	Number (user ID) or object	`"value": 12345` or `"value": { "id": 12345 }`
`notEquals`	Not assigned to user	Number (user ID)	`"value": 12345`
`anyOf`	Assigned to any of these users	Array of IDs	`"value": [12345, 67890]`
`noneOf`	Not assigned to any of these users	Array of IDs	`"value": [12345, 67890]`
`isSet`	Field has any user assigned	N/A	No value needed
`isNotSet`	Field is empty/no user assigned	N/A	No value needed

Examples:

[
  {
    "key": "owner",
    "op": "equals",
    "value": 12345
  },
  {
    "key": "reviewers",
    "op": "anyOf",
    "value": [12345, 67890, 11111]
  },
  {
    "key": "manager",
    "op": "isSet"
  }
]

6. Boolean Fields (bool, isExternal, isDeleted, etc.)

Supported Operations:

Operation	Description	Value Type	Example
`equals`	Exact match	Boolean	`"value": true` or `"value": false`
`notEquals`	Not equal to	Boolean	`"value": true`
`isSet`	Field has any value	N/A	No value needed
`isNotSet`	Field is empty/null	N/A	No value needed

Examples:

[
  {
    "key": "isExternal",
    "op": "equals",
    "value": false
  },
  {
    "key": "isActive",
    "op": "equals",
    "value": true
  }
]

Field Type Reference

Field Type	API Name	Typical Operations	Example Values
Single Line Text	`singleLine`	equals, contains, isSet, isNotSet	"text value"
Multi Line Text	`multiLine`	equals, contains, isSet, isNotSet	"text with\nmultiple lines"
Email	`email`	equals, contains, isSet, isNotSet	"[email protected]"
Card Number	`cardNumber`	equals, contains	"••••••••1234"
Number	`number`	equals, gt, gte, lt, lte, between	100
Currency	`currency`	equals, gt, gte, lt, lte, between	50000
Date	`datePicker`	equals, dayAfter, dayBefore, relativeDateLess	"2024-12-31"
Dropdown	`dropdown`	equals, anyOf, noneOf, isExactly	"option_value"
Multi-Select	`dropdownMulti`	anyOf, noneOf, allOf	["tag1", "tag2"]
User	`usersDropdown`	equals, anyOf, noneOf	12345 or `{id: 12345}`
Multiple Users	`usersDropdownMulti`	anyOf, noneOf	[12345, 67890]
Boolean	`bool`	equals, notEquals	true or false

Examples

Example 1: Apps with Multiple Filters

Get all active apps created in the last 90 days, excluding archived ones:

{
  "filters": [
    {
      "key": "status",
      "op": "equals",
      "value": "active"
    },
    {
      "key": "createdDate",
      "op": "relativeDateLess",
      "value": 90
    },
    {
      "key": "state",
      "op": "noneOf",
      "value": ["archived", "deleted"]
    }
  ]
}

Example 2: Users with Compound Criteria

Get all users who are:

Active or offboarding
Not external
Created by specific owners

{
  "filters": [
    {
      "key": "lifecycleStatus",
      "op": "anyOf",
      "value": ["active", "offboarding"]
    },
    {
      "key": "isExternal",
      "op": "equals",
      "value": false
    },
    {
      "key": "createdBy",
      "op": "anyOf",
      "value": [12345, 67890]
    }
  ]
}

Example 3: Contracts with Range and Date Filters

Get all contracts with:

Amount between $10,000 and $100,000
End date in the next 30 days
Status is active or pending renewal

{
  "filters": [
    {
      "key": "amount",
      "op": "between",
      "value": [1000000, 10000000]
    },
    {
      "key": "endDate",
      "op": "relativeDateLess",
      "value": 30
    },
    {
      "key": "status",
      "op": "anyOf",
      "value": ["active", "renewal_pending"]
    }
  ]
}

HTTP Query Parameter Format

When passing filters as query parameters, URL-encode the JSON:

GET /api/apps?filters=%5B%7B%22key%22%3A%22name%22%2C%22op%22%3A%22contains%22%2C%22value%22%3A%22test%22%7D%5D

Which decodes to:

GET /api/apps?filters=[{"key":"name","op":"contains","value":"test"}]

Example: cURL

curl -X GET "https://api.toriihq.com/users?filters=%5B%7B%22key%22%3A%22lifecycleStatus%22%2C%22op%22%3A%22equals%22%2C%22value%22%3A%22active%22%7D%2C%7B%22key%22%3A%22isExternal%22%2C%22op%22%3A%22equals%22%2C%22value%22%3Afalse%7D%5D" -H "Authorization: Bearer YOUR_API_KEY"

Example: JavaScript


## Example: JavaScript

```javascript
// Get apps containing "slack" created in the last 30 days
const filters = [
  { key: "name", op: "contains", value: "slack" },
  { key: "createdDate", op: "relativeDateLess", value: 30 }
];

const query = new URLSearchParams({
  filters: JSON.stringify(filters),
  fields: "id,name,activeUsersCount"
});

const response = await fetch(
  `https://api.toriihq.com/apps?${query.toString()}`,
  { headers: { Authorization: "Bearer YOUR_API_KEY" } }
);

const { apps } = await response.json();
console.log(apps);

Tips for Effective Filtering

Use contains for text search — more forgiving than equals
Combine multiple filters — API joins them with AND logic
Use anyOf for "match any" — more efficient than multiple filters
Use isSet/isNotSet — to find fields with or without values
Specify fields — limit returned data to reduce response size
Check the response schema — different endpoints return different field sets