8.5Saved filters in the REST API

Saved filters are available on the machine surface under /api/saved-ldap-filters.

In requests and responses the object type is a number:

A creation request looks like this:

{
  "name": "Disabled accounts in Finance",
  "description": "Accounts in Finance with the disabled flag set",
  "objectType": 1,
  "ldapFilter": "(&(department=Finance)(userAccountControl:1.2.840.113556.1.4.803:=2))",
  "baseDn": "OU=Finance,DC=example,DC=com",
  "propertiesToLoad": ["displayName", "sAMAccountName", "whenChanged"],
  "sortBy": null
}

The API also accepts an optional sortBy attribute name, which is stored with the filter and used when it runs; the console form does not show it.

To run a filter, call the results route. The caller supplies only paging; everything else comes from the stored filter:

GET /api/saved-ldap-filters/5d0c…/results?pageSize=100
X-API-Key: <your key>

The response has the same shape as other directory searches: the matching objects under data, and meta.nextContinuationToken and links.next when there is another page. Pass the token as continuationToken to fetch the next page. pageSize defaults to 50 and may not exceed 1000. When nothing matches, the route answers 204 No Content with no body. Runs are rate-limited like other directory searches.

See Chapter 15, REST API for integrators, for authentication and the general response format.

Good practice

• Give filters names that describe the result ("Disabled accounts in Finance"), not the syntax.
• Fill in the description for any filter used by a workflow or agent, saying who depends on it.
• Leave Base DN empty for filters meant to run in several directories.
• Request only the attributes you need.
• Test a new filter in the Directory Browser with a manual search, then save it from the results.
• Before editing a widely used filter, consider creating a new one instead, so existing workflows keep their current behaviour.