# Validate item filter
- Operation ID: `ValidateItemFilter`
- HTTP method: `POST`
- Path: `/items/v2/filter/validate`
- [Human-readable API reference](https://hub.synerise.com/api-reference/ai-suite#tag/Item-filters/operation/ValidateItemFilter)
## Self-contained OpenAPI method
The fenced document below contains this method's documentation and all of its local references. It is self-contained; no category or master specification fetch is required.
```yaml
openapi: 3.0.0
info:
title: Synerise Public API
version: 1.9.1
paths:
/items/v2/filter/validate:
post:
summary: Validate item filter
description: |
This endpoint lets you validate the syntax of a filter and preview its results.
The `parserResult` object in the response validates only the IQL syntax, it does not check if the attributes or contexts referenced in the IQL query exist!
---
**API consumers:** Workspace (Business Profile), Synerise User
**API key permission required:** `ITEMS_FILTER_VALIDATE_READ`
**User role permission required:** `campaigns_recommendations: read`
operationId: ValidateItemFilter
tags:
- Item filters
security:
- JWT: []
parameters:
- name: itemsCatalogId
in: query
required: false
description: |
ID of the item catalog that contains the items tested in the request. If not provided, "default" is assumed - however, the "default" catalog may not exist in your workspace.
**NOTE:** This ID is available in the details the search index or recommendation campaign you want to make test requests for.
schema:
type: string
default: default
- name: exampleItems
in: query
required: false
description: Controls how many example items will be returned
schema:
type: integer
default: 10
requestBody:
content:
application/json:
schema:
description: Request for performing IQL validation
type: object
properties:
filteringString:
type: string
description: "[IQL](https://help.synerise.com/developers/iql) filtering expression"
example: IF("abcd" IN client.tags,discount == 0,discount > 0)
clientUUID:
type: string
description: UUID of the profile which creates the profile context
example: 68df2317-0edb-4cc9-8b39-5ab68325f891
contextItems:
type: array
items:
type: string
example: "12345"
description: itemIds of the items which create the item context
inventoryContext:
description: |
Inventory context used to evaluate inventory-related filters and boosting strategies.
Can be either a single inventory context or a multi-inventory context (set of channel IDs per inventory).
oneOf:
- type: object
description: |
Single inventory context.
properties:
channelIds:
type: array
items:
type: string
description: |
List of channel identifiers used to evaluate inventory-related filters and boosting strategies.
required:
- channelIds
- type: object
description: |
Multi-inventory context where each inventory can have its own set of channel IDs.
properties:
inventoryCatalogs:
type: object
additionalProperties:
type: object
description: |
Context definition for a specific inventory.
properties:
channelIds:
type: array
items:
type: string
description: |
List of channel identifiers for this specific inventory.
description: |
Map of inventory ID to inventory context definition. Each inventory can have its own set of channel IDs.
required:
- inventoryCatalogs
candidateItems:
type: array
items:
type: string
example: "67890"
description: Array of itemIds that will be tested against the IQL expression. You can use this with test items to verify that the query matches the items you expected.
required:
- filteringString
responses:
"200":
description: Validation response
content:
application/json:
schema:
type: object
properties:
filteringString:
type: string
description: "[IQL](https://help.synerise.com/developers/iql) filtering expression"
example: IF("abcd" IN client.tags,discount == 0,discount > 0)
contextItems:
type: array
items:
type: string
example: "12345"
description: itemIds of the items which create the item context
clientUUID:
type: string
description: UUID of the profile which creates the profile context
example: 68df2317-0edb-4cc9-8b39-5ab68325f891
parserResult:
type: object
description: Result of validating the IQL syntax and only the syntax - this result does not inform if the filter returns any results or if the used attributes are filterable.
properties:
valid:
type: boolean
description: True if IQL expression syntax is valid.
message:
type: string
description: Error message when IQL expression is not valid
parsedFilteringString:
type: string
description: Parsed filtering string
required:
- valid
- parsedFilteringString
evaluationResult:
type: object
description: Evaluation including data from the item catalog, configuration, and context items/profiles.
properties:
resultSize:
type: integer
description: How many items meet the conditions of the IQL filtering string in total
modifiedFilteringString:
type: string
description: Filtering string after application of the filtering context. For example, `title != context.title` becomes `title != "Synerise API Reference"`
evaluationErrors:
type: array
description: List of IQL evaluation errors
items:
type: object
properties:
filter:
type: string
description: Name of variable on which the filter is based
message:
type: string
description: Error message
required:
- filter
- message
required:
- resultSize
extracts:
type: object
description: Information about elements that were used anywhere in the filtering string. **Elements are listed only if they were valid.**
properties:
clientExtracts:
type: object
description: Attributes of the context profile
properties:
attributeConstants:
type: array
description: Profile attributes used in the query
items:
type: string
segmentationsConstant:
type: array
description: Segmentations used in the query
items:
type: string
aggregateConstants:
type: array
description: Aggregates used in the query
items:
type: string
expressionConstants:
type: array
description: Expressions used in the query
items:
type: string
TagsConstant:
type: boolean
description: True if context profile's tags were referenced in the query.
contextConstants:
type: array
description: Context elements used in the query
items:
type: string
variables:
type: array
description: Variables used in the query (for example pulled from the context)
items:
type: string
candidateItems:
type: array
description: List of validated candidate items
items:
type: object
properties:
itemId:
type: string
description: ID of an item that was tested against the filtering string
example: "67890"
valid:
type: boolean
description: True if the item meets the conditions of the filtering string
required:
- itemId
- valid
exampleItems:
type: array
items:
type: string
description: Array of itemIds that meet the conditions of the filtering string. The size of this array can be controlled by the `exampleItems` query parameter.
required:
- filteringString
- parserResult
"400":
description: Bad Request
content:
application/json:
schema:
type: object
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
status:
type: integer
description: Status code
error:
type: string
description: Summary of the error
message:
type: string
description: Description of the problem
path:
type: string
description: URL of the requested resource
requestId:
type: string
description: ID of the request which resulted in the error
required:
- timestamp
- status
- message
"500":
description: Service not available
content:
application/json:
schema:
type: object
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
status:
type: integer
description: Status code
error:
type: string
description: Summary of the error
message:
type: string
description: Description of the problem
path:
type: string
description: URL of the requested resource
requestId:
type: string
description: ID of the request which resulted in the error
required:
- timestamp
- status
- message
"502":
description: Catalog not ready
content:
application/json:
schema:
type: object
properties:
timestamp:
type: string
format: date-time
description: Time when the error occurred
status:
type: integer
description: Status code
error:
type: string
description: Summary of the error
message:
type: string
description: Description of the problem
path:
type: string
description: URL of the requested resource
requestId:
type: string
description: ID of the request which resulted in the error
required:
- timestamp
- status
- message
x-snr-doc-urls:
- /api-reference/ai-suite#tag/Item-filters/operation/ValidateItemFilter
x-codeSamples:
- lang: cURL
label: cURL
source: |-
curl --request POST \
--url 'https://api.synerise.com/items/v2/filter/validate?itemsCatalogId=SOME_STRING_VALUE&exampleItems=SOME_INTEGER_VALUE' \
--header 'Authorization: Bearer REPLACE_BEARER_TOKEN' \
--header 'content-type: application/json' \
--data '{"filteringString":"IF(\"abcd\" IN client.tags,discount == 0,discount > 0)","clientUUID":"68df2317-0edb-4cc9-8b39-5ab68325f891","contextItems":["12345"],"inventoryContext":{"channelIds":["string"]},"candidateItems":["67890"]}'
- lang: Python
label: Python
source: |-
import http.client
conn = http.client.HTTPSConnection("api.synerise.com")
payload = "{\"filteringString\":\"IF(\\\"abcd\\\" IN client.tags,discount == 0,discount > 0)\",\"clientUUID\":\"68df2317-0edb-4cc9-8b39-5ab68325f891\",\"contextItems\":[\"12345\"],\"inventoryContext\":{\"channelIds\":[\"string\"]},\"candidateItems\":[\"67890\"]}"
headers = {
'Authorization': "Bearer REPLACE_BEARER_TOKEN",
'content-type': "application/json"
}
conn.request("POST", "/items/v2/filter/validate?itemsCatalogId=SOME_STRING_VALUE&exampleItems=SOME_INTEGER_VALUE", payload, headers)
res = conn.getresponse()
data = res.read()
print(data.decode("utf-8"))
- lang: JavaScript
label: JavaScript
source: |-
const data = JSON.stringify({
"filteringString": "IF(\"abcd\" IN client.tags,discount == 0,discount > 0)",
"clientUUID": "68df2317-0edb-4cc9-8b39-5ab68325f891",
"contextItems": [
"12345"
],
"inventoryContext": {
"channelIds": [
"string"
]
},
"candidateItems": [
"67890"
]
});
const xhr = new XMLHttpRequest();
xhr.withCredentials = true;
xhr.addEventListener("readystatechange", function () {
if (this.readyState === this.DONE) {
console.log(this.responseText);
}
});
xhr.open("POST", "https://api.synerise.com/items/v2/filter/validate?itemsCatalogId=SOME_STRING_VALUE&exampleItems=SOME_INTEGER_VALUE");
xhr.setRequestHeader("Authorization", "Bearer REPLACE_BEARER_TOKEN");
xhr.setRequestHeader("content-type", "application/json");
xhr.send(data);
- lang: Node.js
label: Node.js
source: |-
const http = require("https");
const options = {
"method": "POST",
"hostname": "api.synerise.com",
"port": null,
"path": "/items/v2/filter/validate?itemsCatalogId=SOME_STRING_VALUE&exampleItems=SOME_INTEGER_VALUE",
"headers": {
"Authorization": "Bearer REPLACE_BEARER_TOKEN",
"content-type": "application/json"
}
};
const req = http.request(options, function (res) {
const chunks = [];
res.on("data", function (chunk) {
chunks.push(chunk);
});
res.on("end", function () {
const body = Buffer.concat(chunks);
console.log(body.toString());
});
});
req.write(JSON.stringify({
filteringString: 'IF("abcd" IN client.tags,discount == 0,discount > 0)',
clientUUID: '68df2317-0edb-4cc9-8b39-5ab68325f891',
contextItems: ['12345'],
inventoryContext: {channelIds: ['string']},
candidateItems: ['67890']
}));
req.end();
- lang: PHP
label: PHP
source: |-
setUrl('https://api.synerise.com/items/v2/filter/validate');
$request->setMethod(HTTP_METH_POST);
$request->setQueryData([
'itemsCatalogId' => 'SOME_STRING_VALUE',
'exampleItems' => 'SOME_INTEGER_VALUE'
]);
$request->setHeaders([
'Authorization' => 'Bearer REPLACE_BEARER_TOKEN',
'content-type' => 'application/json'
]);
$request->setBody('{"filteringString":"IF(\\"abcd\\" IN client.tags,discount == 0,discount > 0)","clientUUID":"68df2317-0edb-4cc9-8b39-5ab68325f891","contextItems":["12345"],"inventoryContext":{"channelIds":["string"]},"candidateItems":["67890"]}');
try {
$response = $request->send();
echo $response->getBody();
} catch (HttpException $ex) {
echo $ex;
}
- lang: Java
label: Java
source: |-
HttpResponse response = Unirest.post("https://api.synerise.com/items/v2/filter/validate?itemsCatalogId=SOME_STRING_VALUE&exampleItems=SOME_INTEGER_VALUE")
.header("Authorization", "Bearer REPLACE_BEARER_TOKEN")
.header("content-type", "application/json")
.body("{\"filteringString\":\"IF(\\\"abcd\\\" IN client.tags,discount == 0,discount > 0)\",\"clientUUID\":\"68df2317-0edb-4cc9-8b39-5ab68325f891\",\"contextItems\":[\"12345\"],\"inventoryContext\":{\"channelIds\":[\"string\"]},\"candidateItems\":[\"67890\"]}")
.asString();
servers:
- description: Microsoft Azure EU
url: https://api.synerise.com
- description: Microsoft Azure USA
url: https://api.azu.synerise.com
- description: Google Cloud Platform
url: https://api.geb.synerise.com
tags:
- name: Item filters
components:
securitySchemes:
JWT:
type: http
scheme: bearer
description: |-
JWT Bearer token. The header looks like this: `Bearer {JWT}`
Remember to include the space between 'Bearer' and the token.
Generate a token via the **Authorization** endpoints.
```