HomeDev GuideAPI Reference
Dev GuideAPI ReferenceUser GuideGitHubNuGetDev CommunityDoc feedbackLog In
GitHubNuGetDev CommunityDoc feedback

A **Filter Definition** is a filter template that queries track events and profile properties. The filter definition defines a list of parameters, so multiple event segments can use same filter definition with different parameter values. Optimizely Profile Store has the following types of filter definitions.

  • **Events Filter Definition** – Defines a [KQL query](🔗) template to query track events. The Events filter definition builds a list of device IDs from the matching events.

  • **Profiles Filter Definition** – Defines an OData query template to query profiles. The device IDs are used in event segment  to match profiles.

## Filter Definition properties

The `FilterDefinitionPostRequest` is used in the **Create Filter Definition** endpoint. It contains the following property fields.

  • `Name`_Required_. Name of the filter definition; contains letters (a-z, A-Z) , numbers (0-9), period (.), underline (\_), and dash (-) only.

  • `Description` – Description of the filter definition.

  • `Query`_Required_. The KQL query to find events, or OData query to find profiles. Query could contain Parameters. An example of query is:

  • `Parameters` – The collection of parameter definitions which are used in the Query. Parameter name can contain letters (a-z, A-Z) only. A parameter supports the following types:

    • `bool` – Boolean type.

    • `datetime` – Date time type.

    • `guid` – Globally unique identifier type.

    • `int` – Integer type.

    • `long` –  64-bit integer type.

    • `double` – Double-precision floating-point format type.

    • `string` – String type.

    • `timespan` – Timespan type.

      An example of a parameterized query:


      Where `eventType` and takeTop are the KQL-defined parameters, and name and minimumVisits are OData parameters.

  • `Category` – Filter definition category. `Category` can contain up to 50 characters of any string except backslash (\).

  • `Type` – Filter definition type. Currently, it supports `Events` and `Profiles` type.


The `FilterDefinitionPutRequest` is used in the **Replace Filter Definition** endpoint. It contains all the properties in `FilterDefinitionPostRequest` except the `Name` field.

## Filter Definition methods

### Get filter definition

Endpoint: **GET api/v2.0/filterdefinitions/{id}**

Returns HTTP 200 OK with the filter definition specified by {id}.

Example of response body:

### List filter definitions

Endpoint: **GET api/v2.0/filterdefinitions**

List all filter definitions in the current environment. The result window size is limited to the top 10,000 records.


Unlike profiles and events, there is no OData query support to match filter definitions with given conditions.

### Create filter definition

Endpoint: **POST api/v2.0/filterdefinitions**

Example of request body (FilterDefinitionPostRequest):

Example of response body:


Prefix fd\_ is added to the filter defintion name as the value of id property.

### Replace filter definition

Endpoint: **PUT api/v2.0/filterdefinitions/{id}**


A filter definition cannot be replaced if any segment is using it. By doing so, a list of affected segments return in the error response.

Remove all filters connected to the filter definition in the affected segments before replacing it.

Example of request body (`FilterDefinitionPutRequest`):

Example of response body:

### Delete filter definition

Endpoint: **DELETE api/v2.0/filterdefinitions/{id}**


You cannot delete a filter definition if any segment is using it. If you try to do so, a list of affected segments is returned in the error response. Before deleting a filter definition, remove the filters connected to it in the affected segments.

### Preview filter definition

Endpoint: **POST api/v2.0/filterdefinitions/{id}/preview **

You can preview a filter definition result, mainly to check if the result produced by a query is correct.

You should create a filter definition before previewing it. Then, request the preview endpoint with a request body.

Example of a filter definition:

Example of a request body (`FilterDefinitionPreviewRequest`):