AI Suite (Nov 5, 2024, 1:06:06 PM)

Download OpenAPI specification:Download

Welcome to Synerise API Reference! We hope that you'll enjoy your stay here.

If you need help with our services, feel free to contact us at support@synerise.com.

Authentication

JWT

Synerise uses JSON Web Token (JWT) as the authorization method. The token is generated by the auth/login endpoint. You need to include it in the Authorization header of your requests, with a Bearer prefix. See this simplified example of a call:

curl -X GET https://api.synerise.com/v4/clients \
-H 'Accept: application/json' \
-H 'Api-Version: 4.4' \
-H 'Authorization: Bearer eyJhbGciOiJSzZXIiLCJjdGQiOjE1NTI0NjMzMjg4NjIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsIm5tZSI' \
-H 'Content-Type: application/json'

Remember to include a space between Bearer and the token.

The token is valid for one hour (unless configured differently). You can request a refreshed key for the session by using the auth/refresh endpoint before the current token expires.

You can verify your JWT signature by using the public key.

Security Scheme Type	HTTP
HTTP Authorization Scheme	bearer

TrackerKey

Authorization by tracker key sent in a token query parameter. This may be the same key as used in the tracking code of the website. For details, see this article: https://help.synerise.com/developers/web/installation-and-configuration/#creating-a-tracking-code.

Security Scheme Type	API Key
Query parameter name:	token

Authorization

Methods to authorize and obtain JWT token required by our API endpoints

Log in as User

Authenticate as a User.

Note: To perform operations within a Workspace, you must select a Workspace.

This method does not require a Synerise authorization token.

Request Body schema: application/json

username required	string The login (email address) of the user
password required	string The user's password
deviceId	string Identifier of user's current device
externalProviderToken	string
externalProviderType	string Value: "GOOGLE"

Responses

Request samples

Content type

application/json

{"username": "string",
"password": "string",
"deviceId": "string",
"externalProviderToken": "string",
"externalProviderType": "GOOGLE"
}

Response samples

200

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Verify User multi-factor authentication

Authenticate as a User with multi-factor authentication.

Note: To perform operations within a Workspace, you must select a Workspace.

API consumer who can use this method: Synerise User
This method is available to all authenticated users, before and after multi-factor authentication is confirmed.

Authorizations:

JWT

query Parameters

mfaType

required

string

Enum: "TOTP_AUTHENTICATOR" "EMAIL"

Type of multi-factor authentication

Request Body schema: application/json

verificationCode required	string Multi-factor verification code
deviceId	string
externalProviderToken	string
externalProviderType	string Value: "GOOGLE"

Responses

Request samples

Content type

application/json

{"verificationCode": "string",
"deviceId": "string",
"externalProviderToken": "string",
"externalProviderType": "GOOGLE"
}

Response samples

200

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Select Workspace

After logging in as a User, select a Workspace where you want to perform operations.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

path Parameters

businessProfileUUID

required

string <uuid>

UUID of the workspace

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/uauth/auth/login/user/profile/%7BbusinessProfileUUID%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
423

Content type

application/json

{"consumer": {"type": "USER",
"businessProfileId": 0,
"name": "string",
"id": 0,
"authorities": ["string"
],
"roles": "string"
},
"token": "string"
}

Get Workspaces

Retrieve a list of Workspaces available to the user.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/uauth/business-profile/ 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"businessProfileGuid": "string",
"logo": "string",
"name": "string",
"id": 0,
"created": "2019-08-24T14:15:22Z",
"subdomain": "string",
"ipRestricted": true,
"mfaRequired": true
}
]

Get current Workspace

Retrieve information about the currently selected workspace.

API consumer who can use this method: Synerise User
This method is available to all fully-authenticated users (multifactor confirmation required, if enabled).

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/uauth/business-profile/current 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

{"selected": true,
"data": {"id": 0,
"name": "string",
"logo": "string",
"businessProfileGuid": "string",
"created": "2019-08-24T14:15:22Z",
"subdomain": "string",
"ipRestriction": "OFF",
"mfaRestriction": "OFF"
}
}

Log in as Workspace

Obtain a new Workspace JWT Token.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey

required

string

Workspace API key

WARNING: Workspace API keys can be used to access all customer data and manage the workspace. They should only be used for server-to-server communication in integrations. DO NOT use workspace API keys in your mobile applications or websites.

Responses

Request samples

Content type

application/json

{"apiKey": "64c09614-1b2a-42f7-804d-f647243eb1ab"
}

Response samples

200
400
401

Content type

application/json

{"token": "string"
}

Refresh a Profile token

Retrieve a refreshed JWT Token to prolong the session.

The current token must still be active at the time of the request.

API consumers who can use this method: Profile (formerly client), Anonymous profile (formerly client)
This method does not require a Synerise authorization token.

Authorizations:

JWT

Request Body schema: application/json

apiKey

required

string

Profile (formerly "Client") API key

Responses

Request samples

Content type

application/json

{"apiKey": "string"
}

Response samples

200
401

Content type

application/json

{"token": "string",
"expiration": 1649283173,
"created": 1649277173668,
"origin": "SYNERISE",
"customId": "card123",
"realm": "client"
}

Authenticate as Profile

Obtain a new JWT for a Profile. If an account for the Profile does not exist and the identityProvider is different than SYNERISE, this request creates an account.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey required	string Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Authenticate Profile with a server

Obtain a new JWT for a Profile. This method is designed to be used from a backend server that handles login requests and communicates with Synerise to execute them.
If an account for the Profile does not exist and the identityProvider is different than SYNERISE, this request creates an account.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SAUTH_SERVER_LOGIN_CLIENT_CREATE

Request Body schema: application/json

ipAddress required	string The IP address of the client device that is logging in.
apiKey required	string Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"ipAddress": "string",
"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Authenticate as Profile (conditional)

Obtain a new JWT token for a Profile.

If the account does not exist, an account is not created.
If any additional conditions are required for logging in, the response is HTTP200 and lists the conditions.
Note that using this endpoint requires authenticating as an anonymous Profile first.
This method does not require a Synerise authorization token.

Authorizations:

JWT

Request Body schema: application/json

apiKey required	string Profile (formerly "Client") API key
identityProvider required	string Enum: "SYNERISE" "FACEBOOK" "OAUTH" "APPLE" "GOOGLE" "UNKNOWN" The identity provider.
identityProviderToken	string Third-party authentication token used to authenticate with the Identity Provider. Required if `identityProvider` is different than `SYNERISE`.
email	string Profile email. Required if `identityProvider` is `SYNERISE` and email is the unique identifier (default setting).
customId	any Profile customId. Required if `identityProvider` is `SYNERISE` and customId is the unique identifier (see https://hub.synerise.com/docs/settings/configuration/non-unique-emails/).
password	string Profile password. Required if `identityProvider` is `SYNERISE`.
uuid	string Profile UUID. Required if `identityProvider` is `SYNERISE`.
deviceId	string Unique Android or iOS device ID
	object This object contains the marketing agreements of the Profile. You can also pass the values as strings (`"true"`;`"True"`/`"false"`;`"False"`) or integers (`1` for true and `0` for false).
	object This object contains custom attributes that can have any name (except for reserved attributes, see warning below) and data type, as required by your integration. The attribute names can't include any characters that match the pattern (ECMA flavor): `/[\r\n\u2028\u2029\u00AD\u0000\uFE00-\uFE0F]/` String values: can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`) If you want to send a date/time attribute for use in analytics, take the following into account: The date/time should be formatted according to ISO 8601. The time zone of the workspace affects dates/times in the attributes that DON'T have a defined timezone. Example: `2023-10-09T12:00:00` doesn't have a timezone indicator and will be considered as a time in the workspace's time zone. `2023-10-09T12:00:00+02:00` has a timezone indicator (`+02:00`), so the timezone of the workspace doesn't affect it. `2023-10-09T12:00:00Z` is a time in the UTC time zone (denoted by the `Z` at the end), so the timezone of the workspace doesn't affect it. WARNING: Some attributes are reserved and cannot be sent. If you send them, they are ignored. Click to expand the list of reserved attributes `email` `clientId` `phone` `customId` `uuid` `firstName` `lastName` `displayName` `company` `address` `city` `province` `zipCode` `countryCode` `birthDate` `sex` `avatarUrl` `anonymous` `agreements` `tags` `businessProfileId` `time` `ip` `source` `newsletter_agreement` `custom_identify` `firstname` `lastname` `created` `updated` `last_activity_date` `birthdate` `external_avatar_url` `displayname` `receive_smses` `receive_push_messages` `receive_webpush_messages` `receive_btooth_messages` `receive_rfid_messages` `receive_wifi_messages` `confirmation_hash` `ownerId` `zipCode` `anonymous_type` `country_id` `geo_loc_city` `geo_loc_country` `geo_loc_as` `geo_loc_country_code` `geo_loc_isp` `geo_loc_lat` `geo_loc_lon` `geo_loc_org` `geo_loc_query` `geo_loc_region` `geo_loc_region_name` `geo_loc_status` `geo_loc_timezone` `geo_loc_zip` `club_card_id` `type` `confirmed` `facebookId` `status`
tags	Array of strings Tags can be used to group profiles. Tag names (strings): can't include variation selectors (`[\uFE00-\uFE0F]`), unless there are other characters in the string. can't include the "null" control character (`\u0000`)

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"identityProvider": "SYNERISE",
"identityProviderToken": "string",
"email": "string",
"customId": null,
"password": "string",
"uuid": "string",
"deviceId": "string",
"agreements": {"email": false,
"sms": false,
"push": false,
"webPush": false,
"bluetooth": false,
"rfid": false,
"wifi": false
},
"attributes": {"property1": null,
"property2": null
},
"tags": ["string"
]
}

Response samples

Content type

application/json

{"conditions": ["string"
],
"status": "SUCCESS",
"token": "string",
"expiration": 1649283173,
"created": 1649277173668,
"origin": "SYNERISE",
"customId": "card123",
"realm": "client"
}

Authenticate anonymously

Obtain a new JWT for an anonymous Profile. The token can be used and refreshed in the same way as tokens of registered Profiles.

This method does not require a Synerise authorization token.

Request Body schema: application/json

apiKey required	string Profile (formerly "Client") API key
uuid required	string UUID of the Profile. It is a unique identifier. The value can't include any characters that match the pattern (ECMA flavor): `/([\uD800-\uDBFF][\uDC00-\uDFFF])\|([\r\n\u2028\u2029\u00AD]\|[\uFE00-\uFE0F]\|[\u0000])/`
deviceId	string Unique iOS or Android device identifier.

Responses

Request samples

Content type

application/json

{"apiKey": "string",
"uuid": "07243772-008a-42e1-ba37-c3807cebde8f",
"deviceId": "string"
}

Response samples

200
401

Content type

application/json

{"token": "eyJhbGciOiJSUzUxMiJ9.eyJzdinvalidwYmZkM2FkNDg2ZjQ3ZGRiMjE5MSIsImF1ZCI6IkFQSSIsInJsbSI6ImFub255bW91c19jbGllbnQiLCJjdGQiOjE1NTMwMDQxNTkxNTEsImVtbCI6IjYyMjM3NmY4LTAwMDAtMjIyMi1kN2Y5LTA3MGZhOTU2ZTk2M0Bhbm9ueW1vdXMuaW52YWxpZCIsImF1dGgiOiJINHNJQUFBQUFBQUFBSXVPQlFBcHUwd05BZ0FBQUE9PSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo0OCwiY2xJZCI6NDMzMjMwMjg4LCJleHAiOjE1NTMwMDcxNTksImFwayI6IjVBRUFBM0Q1LUUxNDctQzdFQi1ENTlFLUJDRjUwMTA5QTNEMSJ9.QOmSqrneR4mJFv4JdxTYsw_wGcDawDsVQuB-GVTcPPwijiP7lQ_Jzqq2Mypg1BS6WFlfGB8fzqCY9iMF_TdtjmoB4xBrY95ylU8L9qto-9Cw5x5TURkfxq31eryiHe2IteRAEtoVzYg2_s9QhlH6ANVcFOVp8dMno0V9bfMYfeSQa3FkjEbxFsseHkMOiADmp9-tOGtLXO942Ir-2W_Hz3Utlpt4erz0dVJBw8a-mFavPA8EEDWR7ACJNocrVHFkS3wFISh3LqLn6KkXiowaynKlJOEHGctuahzKmF3ZOJ1BvGgKohxF9OXvQs9IdmCfWhYsLr5Q2p04TJJ-MyvTipuggKVioh8mHmOFdfnN-Zused6tXzhZtKPUWTmM8cBKoAOBHExxcMQ8SVSjxnw_7_eLKm7S2wNpu0V-tiPZPCH4wYZXtWBYjmfy0V9ydjXnNunXfgxKixLeFNnONUXxEuqPLvM_xAuonQBXVN4nYrgJv8p8U6_ZlGMPjJq1szfcuBZnzI34LSEWx_nSof0XC5Czm8iG_ihG8naivNWS8h-Q-qKMP_3PPFsLSH4Egh03pH93EJUuNAeSO4RGfUX1wzMvrv1nBC1SM660uFMbq-wkplFBbKnHKMYe-qRs1-lZPG5PwPWJJdpGqOUzbnoMOJYmiq06OHHVQyJSkcEHLCk"
}

Search

AI-powered search engine management and usage

Full-text items search

Retrieves items that match a full-text query from a search index or a suggestion index. The results can be filtered and sorted.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

query required	string Query text to use in the search
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string Correlation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchId	string Deprecated DEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings Example: filterGeoPoints=34.052235,-118.243685&filterGeoPoints=15.0,65.0 The definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the `filterAroundRadius` parameter. Example input: `["34.052235,-118.243685"]` Given two geo-points, the results will be limited to a rectangular area. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. Example input: `["50,-100", "25,150"]` Given three or more geo-points, the results will be limited to a polygonal area. Example input: `["50,0", "40,20", "-20,10"]`
filterAroundRadius	integer <int32> Default: 1000 Example: filterAroundRadius=5000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
displayAttributes	Array of strings Example: displayAttributes=title&displayAttributes=price List of ad hoc attributes that will be returned for each found item
context	Array of strings Example: context=mobile&context=listing List of context strings for a search query
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the `facets` parameter.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `true`, pagination metadata is included in the response body. When `false`, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilter	string Example: distinctFilter={"attribute": "color", "maxNumItems": 3} DistinctFilter JSON as an URL-encoded string
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers[ items ] Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/query?query=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&correlationId=SOME_STRING_VALUE&searchId=SOME_STRING_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685%2C15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=SOME_ARRAY_VALUE&context=SOME_ARRAY_VALUE&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=SOME_ARRAY_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Full-text items search

Retrieves items that match a full-text query from a search index or a suggestion index. The results can be filtered and sorted.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json

Request for performing full-text search

query required	string Query text to use in the search
page	integer <int32> Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean When `true`, pagination metadata is included in the response body. When `false`, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUID	string UUID of the profile which creates the profile context
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string `correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
searchId	string Deprecated DEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoints	string Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings The definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the `filterAroundRadius` parameter. Example input: `["34.052235,-118.243685"]` Given two geo-points, the results will be limited to a rectangular area. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. Example input: `["50,-100", "25,150"]` Given three or more geo-points, the results will be limited to a polygonal area. Example input: `["50,0", "40,20", "-20,10"]`
filterAroundRadius	integer <int32> Default: 1000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
	object A key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the `facets` parameter.
context	Array of strings List of context strings for a search query
displayAttributes	Array of strings List of ad hoc attributes that will be returned for each found item
	object Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers[ items ] List of query rules that will not be applied.

Responses

Request samples

Content type

application/json

{"query": "string",
"page": 0,
"limit": 10,
"sortBy": "string",
"ordering": "desc",
"includeMeta": true,
"clientUUID": "68df2317-0edb-4cc9-8b39-5ab68325f891",
"personalize": true,
"correlationId": "string",
"searchId": "string",
"sortByMetric": "TransactionsPopularity",
"sortByGeoPoints": "34.052235,-118.243685",
"filterGeoPoints": ["34.052235,-118.243685",
"15.0,65.0"
],
"filterAroundRadius": 2000,
"filters": "string",
"facets": ["string"
],
"customFilteredFacets": {"brand": "price > 100",
"price": "brand == foo"
},
"facetsSize": 2000,
"maxValuesPerFacet": 50,
"caseSensitiveFacetValues": false,
"includeFacets": "all",
"context": ["mobile",
"listing"
],
"displayAttributes": ["title",
"price"
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 1,
"levelRangeModifier": 0
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
]
}

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Autocomplete items search

Retrieves items that match a query from a search index or a suggestion index. The results can be filtered and sorted. The results of this search type are not cached.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

query required	string Query text to use in the search
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings Example: filterGeoPoints=34.052235,-118.243685&filterGeoPoints=15.0,65.0 The definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the `filterAroundRadius` parameter. Example input: `["34.052235,-118.243685"]` Given two geo-points, the results will be limited to a rectangular area. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. Example input: `["50,-100", "25,150"]` Given three or more geo-points, the results will be limited to a polygonal area. Example input: `["50,0", "40,20", "-20,10"]`
filterAroundRadius	integer <int32> Default: 1000 Example: filterAroundRadius=5000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
displayAttributes	Array of strings Example: displayAttributes=title&displayAttributes=price List of ad hoc attributes that will be returned for each found item
context	Array of strings Example: context=mobile&context=listing List of context strings for a search query
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the `facets` parameter.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `true`, pagination metadata is included in the response body. When `false`, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
distinctFilter	string Example: distinctFilter={"attribute": "color", "maxNumItems": 3} DistinctFilter JSON as an URL-encoded string
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers[ items ] Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/autocomplete?query=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685%2C15.0%2C65.0&filterAroundRadius=5000&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=SOME_ARRAY_VALUE&context=SOME_ARRAY_VALUE&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&distinctFilter=%7B%22attribute%22%3A%20%22color%22%2C%20%22maxNumItems%22%3A%203%7D&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=SOME_ARRAY_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Autocomplete items search

Retrieves items that match a query from a search index or a suggestion index. The results can be filtered and sorted. The results of this search type are not cached.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema: application/json

Request for performing an autocomplete search

query required	string Query text to use in the search
page	integer <int32> Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean When `true`, pagination metadata is included in the response body. When `false`, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUID	string UUID of the profile which creates the profile context
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoints	string Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings The definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the `filterAroundRadius` parameter. Example input: `["34.052235,-118.243685"]` Given two geo-points, the results will be limited to a rectangular area. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. Example input: `["50,-100", "25,150"]` Given three or more geo-points, the results will be limited to a polygonal area. Example input: `["50,0", "40,20", "-20,10"]`
filterAroundRadius	integer <int32> Default: 1000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
	object A key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the `facets` parameter.
context	Array of strings List of context strings for a search query
displayAttributes	Array of strings List of ad hoc attributes that will be returned for each found item
	object Distinct filters regulate how many items with the same value of a particular attribute can be returned.
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers[ items ] List of query rules that will not be applied.

Responses

Request samples

Content type

application/json

{"query": "string",
"page": 0,
"limit": 10,
"sortBy": "string",
"ordering": "desc",
"includeMeta": true,
"clientUUID": "68df2317-0edb-4cc9-8b39-5ab68325f891",
"sortByMetric": "TransactionsPopularity",
"sortByGeoPoints": "34.052235,-118.243685",
"filterGeoPoints": ["34.052235,-118.243685",
"15.0,65.0"
],
"filterAroundRadius": 2000,
"filters": "string",
"facets": ["string"
],
"customFilteredFacets": {"brand": "price > 100",
"price": "brand == foo"
},
"facetsSize": 2000,
"maxValuesPerFacet": 50,
"caseSensitiveFacetValues": false,
"includeFacets": "all",
"context": ["mobile",
"listing"
],
"displayAttributes": ["title",
"price"
],
"distinctFilter": {"attribute": "string",
"maxNumItems": 1,
"levelRangeModifier": 0
},
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
]
}

Response samples

200
500

Content type

application/json

Example

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string",
"suggestions": [{"text": "string",
"highlighted": "string",
"score": 1
}
],
"usedSuggestion": {"text": "string",
"highlighted": "string",
"score": 1
}
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Get deleted searches

Retrieve the searches deleted from a profile's history.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_RECENT_SEARCH_READ

Authorizations:

JWT

TrackerKey

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index that the query relates to

query Parameters

clientUUID

required

string

Example: clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1

UUID of the profile for which the query is performed

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/deleted-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
400

Content type

application/json

[{"query": "string",
"match": "query",
"timestamp": "2019-08-24T14:15:22Z"
}
]

Soft-delete a recent search

Delete a recent search from the history accessible to a profile. The search remains in the database and you can retrieve it by using this endpoint.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_RECENT_SEARCH_CREATE

Authorizations:

JWT

TrackerKey

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index that the query relates to

query Parameters

clientUUID

required

string

Example: clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1

UUID of the profile for which the query is performed

Request Body schema: application/json

Request for deleting search query

query	string Deleted search query. Required if `match` field is set to `query`.
match	string Default: "query" Tells how to match this deleted search on recent searches. `query`: matches only recent searches with provided query `all`: matches all recent searches
timestamp	string <date-time> Time when the search was deleted. If not present current time is taken.

Responses

Request samples

Content type

application/json

{"query": "string",
"match": "query",
"timestamp": "2019-08-24T14:15:22Z"
}

Response samples

400

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Get recent searches

Get a profile's recent searches from a particular index.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_RECENT_SEARCH_READ

Authorizations:

JWT

TrackerKey

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index that the query relates to

query Parameters

clientUUID required	string Example: clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1 UUID of the profile for which the query is performed
windowSize	integer >= 1 Default: 15 Maximum number of recent searches to be returned. NOTE: The provided query parameter has priority over the configuration provided in this endpoint. If the parameter is not provided, the default value does not override the configuration.
timeUnit	string Default: "DAYS" Enum: "YEARS" "MONTHS" "WEEKS" "DAYS" "HOURS" "MINUTES" "SECONDS" The time unit. Used in conjunction with `timeValue`. NOTE: The provided query parameter has priority over the configuration provided in this endpoint. If the parameter is not provided, the default value does not override the configuration.
timeValue	integer >= 1 Default: 30 The amount of time units. Used in conjunction with `timeUnit`. NOTE: The provided query parameter has priority over the configuration provided in this endpoint. If the parameter is not provided, the default value does not override the configuration.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/recent-searches?clientUUID=e0097757-d1e2-44ac-ba3c-d97979a354c1&windowSize=SOME_INTEGER_VALUE&timeUnit=SOME_STRING_VALUE&timeValue=SOME_INTEGER_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
400

Content type

application/json

["string"
]

Visual Search

Visual Search methods

Visual items search

Retrieves items that match an image. The results can be filtered and sorted.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

query Parameters

url required	string URL of the image to be used in the visual search
clientUUID	string UUID of the profile for which the search is performed
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string Correlation ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
searchId	string Deprecated DEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoint	string Example: sortByGeoPoint=34.052235,-118.243685 Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings Example: filterGeoPoints=34.052235,-118.243685&filterGeoPoints=15.0,65.0 The definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the `filterAroundRadius` parameter. Example input: `["34.052235,-118.243685"]` Given two geo-points, the results will be limited to a rectangular area. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. Example input: `["50,-100", "25,150"]` Given three or more geo-points, the results will be limited to a polygonal area. Example input: `["50,0", "40,20", "-20,10"]`
filterAroundRadius	integer <int32> Default: 1000 Example: filterAroundRadius=5000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filterAnchor	string Example: filterAnchor=0.2,0.8 Anchor (`{width},{height}`) by which the visual results data will be filtered. `{width},{height}` correspond to normalized image coordinates, i.e. they are in range [0,1]. Anchor (0,0) corresponds to the top-left pixel of an image.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
displayAttributes	Array of strings Example: displayAttributes=title&displayAttributes=price List of ad hoc attributes that will be returned for each found item
context	Array of strings Example: context=mobile&context=listing List of context strings for a search query
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the `facets` parameter.
page	integer <int32> Default: 1 Example: page=4 Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> [ 0 .. 500 ] Default: 20 Example: limit=10 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean Default: false When `true`, pagination metadata is included in the response body. When `false`, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers[ items ] Example: excludeQueryRules=2&excludeQueryRules=5 List of query rules that will not be applied.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/visual?url=SOME_STRING_VALUE&clientUUID=SOME_STRING_VALUE&personalize=SOME_BOOLEAN_VALUE&correlationId=SOME_STRING_VALUE&searchId=SOME_STRING_VALUE&sortByMetric=SOME_STRING_VALUE&sortByGeoPoint=34.052235%2C-118.243685&filterGeoPoints=34.052235%2C-118.243685%2C15.0%2C65.0&filterAroundRadius=5000&filterAnchor=0.2%2C0.8&filters=SOME_STRING_VALUE&facets=SOME_ARRAY_VALUE&facetsSize=SOME_INTEGER_VALUE&maxValuesPerFacet=SOME_INTEGER_VALUE&caseSensitiveFacetValues=SOME_BOOLEAN_VALUE&displayAttributes=SOME_ARRAY_VALUE&context=SOME_ARRAY_VALUE&includeFacets=SOME_STRING_VALUE&page=4&limit=10&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&ignoreQueryRules=SOME_BOOLEAN_VALUE&excludeQueryRules=SOME_ARRAY_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string"
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Visual items search

Retrieves items that match an image. The results can be filtered and sorted.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_SEARCH_SEARCH_READ

Authorizations:

TrackerKey

JWT

path Parameters

indexId

required

string

ID of the index to be used in the search operation

Request Body schema:
application/json
application/json
multipart/form-data

Request for performing visual search

url required	string URL of the image to be used in the visual search
page	integer <int32> Page number to return for pagination. The first page has the index `1`.
limit	integer <int32> [ 0 .. 500 ] Default: 20 The number of items to return per page
sortBy	string Name of the attribute by which the data will be sorted. Sorting by attribute may cause a promoted item to be in a different position that defined in a query rule.
ordering	string Default: "asc" Enum: "desc" "asc" Sorting order
includeMeta	boolean When `true`, pagination metadata is included in the response body. When `false`, the data is included in the response headers: Link: links to neighbors, first, and last pages in pagination. X-Pagination-Total-Count: total number of items on all pages X-Pagination-Total-Pages: total number of pages X-Pagination-Page: current page X-Pagination-Limit: maximum number of items on a page X-Pagination-Sorted-By: parameter that the items were sorted by X-Pagination-Ordering: sorting direction
clientUUID	string UUID of the profile which creates the profile context
personalize	boolean Default: true If set to `false`, the search result is not personalized.
correlationId	string `correlationId` of the request which this event relates to, for example a recommendation or search request (the parameter is included in the response to that request).
searchId	string Deprecated DEPRECATED - use correlationId instead Search ID for pagination. If a search with the ID was performed recently (last 10 minutes), the cached results will be used. Do not send this if sortBy/filters/sorting order, etc. have changed - the cached results may have different order or may match different filters.
sortByMetric	string Enum: "TransactionsPopularity" "PageVisitsPopularity" Name of the metric by which the data will be sorted
sortByGeoPoints	string Geo-point (`{latitude},{longitude}`) for data sorting. Results are sorted by distance from this point. `ordering: asc` means "closest first".
filterGeoPoints	Array of strings The definition of a geographical area to filter by. Given one geo-point, the results will be limited to a radius around a point. To override the default radius (1000 meters), provide the `filterAroundRadius` parameter. Example input: `["34.052235,-118.243685"]` Given two geo-points, the results will be limited to a rectangular area. The first point defines the upper-left corner of the rectangle and the second is the lower-right corner. Example input: `["50,-100", "25,150"]` Given three or more geo-points, the results will be limited to a polygonal area. Example input: `["50,0", "40,20", "-20,10"]`
filterAroundRadius	integer <int32> Default: 1000 Radius in meters to be used when filtering using geo-location. Can only be used when filtering by a single geo-point.
filterAnchor	string Anchor (`{width},{height}`) by which the visual results data will be filtered. `{width},{height}` correspond to normalized image coordinates, i.e. they are in range [0,1]. Anchor (0,0) corresponds to the top-left pixel of an image.
filters	string IQL query string. For details, see the Help Center.
facets	Array of strings A list of attributes for which facets will be returned. A single `*` value matches all facetable attributes. To determine which groups of facets should be returned, use the `includeFacets` parameter.
	object A key-value map that takes attributes as keys and IQL query strings as values. For each key a facet is returned that includes only the items filtered by the provided IQL query string.
facetsSize	integer [ 1 .. 10000 ] Default: 2000 Determines how many items will be used for facets aggregation.
maxValuesPerFacet	integer [ 1 .. 1000 ] Default: 50 Determines how many values will be retrieved per facet.
caseSensitiveFacetValues	boolean Default: false Specifies whether facets aggregation should be case sensitive.
includeFacets	string Default: "filtered" Enum: "all" "filtered" "unfiltered" "none" Determines which groups of facets will be returned: both filtered and unfiltered; just filtered; just unfiltered; or no group at at all. To determine which attributes should be returned as facets in each group, use the `facets` parameter.
context	Array of strings List of context strings for a search query
displayAttributes	Array of strings List of ad hoc attributes that will be returned for each found item
ignoreQueryRules	boolean Default: false If set to `true`, query rules are not applied.
excludeQueryRules	Array of integers[ items ] List of query rules that will not be applied.

Responses

Request samples

Content type

{"url": "string",
"page": 0,
"limit": 10,
"sortBy": "string",
"ordering": "desc",
"includeMeta": true,
"clientUUID": "68df2317-0edb-4cc9-8b39-5ab68325f891",
"personalize": true,
"correlationId": "string",
"searchId": "string",
"sortByMetric": "TransactionsPopularity",
"sortByGeoPoints": "34.052235,-118.243685",
"filterGeoPoints": ["34.052235,-118.243685",
"15.0,65.0"
],
"filterAroundRadius": 2000,
"filterAnchor": "0.2,0.8",
"filters": "string",
"facets": ["string"
],
"customFilteredFacets": {"brand": "price > 100",
"price": "brand == foo"
},
"facetsSize": 2000,
"maxValuesPerFacet": 50,
"caseSensitiveFacetValues": false,
"includeFacets": "all",
"context": ["mobile",
"listing"
],
"displayAttributes": ["title",
"price"
],
"ignoreQueryRules": false,
"excludeQueryRules": [2,
5
]
}

Response samples

200
500

Content type

application/json

{"data": [{"itemName": "TV",
"itemId": 87257843345,
"_promotedByRules": [475,
477
]
}
],
"extras": {"filteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"unfilteredResultFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"customFilteredFacets": {"brand": {"X-brand": 1,
"Y-brand": 3
},
"salePrice.value": {"max": 201.99,
"min": 14.99
}
},
"correlationId": "string",
"searchId": "string"
},
"meta": {"pagination": {"limit": 0,
"page": 0,
"pages": 0,
"total": 0
}
}
}

Search Analytics

Statistics for the AI-powered search engine

Get queries stats summary

Retrieves the statistics of all queries or a single query defined in the request.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchType	string Default: "all" Enum: "fullTextSearch" "autocomplete" "listing" "visual" "all" Search type for which stats will be retrieved.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/stats/queries/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&query=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0
}

Get top query statistics

Retrieves the 1000 most popular queries.

IMPORTANT: Don't use this endpoint for displaying most popular queries to end users when they're searching. Instead, use search/v2/indices/{indexId}/list, where indexId is a suggestion index.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchType	string Default: "all" Enum: "fullTextSearch" "autocomplete" "listing" "visual" "all" Search type for which stats will be retrieved.
queryFilter	string Default: "queries" Enum: "queries" "queriesWithNoResults" "queriesWithUsedSuggestions" Queries for which stats will be retrieved.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.
withFilters	string Enum: "true" "false" Switch to display search statistics with enabled filters or without filters.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/stats/queries/top?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&query=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE&queryFilter=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE&withFilters=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"count": 0
}
]

Get filters stats

Retrieves the statistics of filters used in searches.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

filterName	string Example: filterName=brand Name of the filterable attribute. If present top values of this filter are returned.
dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/stats/filters/summary?filterName=brand&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"filterName": "string",
"count": 0
}
]

Get rules stats

Retrieves the statistics of applied rules.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

indexId

required

string

Example: 4add1a1fa877c1651906bb22c9dfd37a1618852272

ID of the index for which the stats are requested

query Parameters

dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/%7BindexId%7D/stats/rules/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"ruleId": 0,
"count": 0
}
]

Get queries summary for multiple indices

Retrieves the statistics of all queries or a single query defined in the request for multiple indices.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_STATS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

indexId required	Array of strings List of indices ids for which the stats are requested.
dateFrom	string <date> Upper bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
dateTo	string <date> Lower bound of the interval for which the statistics will be retrieved. If not specified, the interval is last 7 days.
query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
searchType	string Default: "all" Enum: "fullTextSearch" "autocomplete" "listing" "visual" "all" Search type for which stats will be retrieved.
groupBy	string Value: "date" Attribute for which retrieved stats will be grouped.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/search/v2/indices/stats/queries/summary?indexId=SOME_ARRAY_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&query=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE&groupBy=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"indexId": "4add1a1fa877c1651906bb22c9dfd37a1618852272",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0
}
}
]

Query stats summary

Retrieve the statistics of all queries or a single query defined in the request.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}

Query stats grouped by date

Retrieves query statistics grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries

Retrieve the statistics of the 1000 most popular queries.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries grouped by date

Retrieve the statistics of the 1000 most popular queries, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries/group/date/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"totalSuggestionsUsed": 0,
"uniqueUsers": 0
}
}
]
}
]

Stats of queries with suggestions used

Retrieves the statistics of queries where the customer accepted a suggestion.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}

Stats of queries with suggestions used grouped by date

Retrieves the statistics of queries where a customer accepted a suggestion, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries with used suggestions

Retrieves the statistics of the 1000 most popular queries where the customer accepted a suggestion.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}
}
]

Stats of top queries with used suggestions grouped by date

Retrieves the statistics of the 1000 most popular queries where the customer accepted a suggestion, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-suggestions-used/group/date/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"query": "string",
"stats": {"averageClickPosition": 0,
"averageOrderValue": 0,
"clickThroughRate": 0,
"conversionRate": 0,
"conversions": 0,
"noResultsCount": 0,
"revenue": 0,
"totalClicks": 0,
"totalCount": 0,
"uniqueUsers": 0
}
}
]
}
]

Stats of queries with no results

Retrieves the statistics of searches which returned no results.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

{"totalCount": 0
}

Stats of queries with no results grouped by date

Retrieves the statistics of searches which returned no results, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": {"totalCount": 0
}
}
]

Get stats of top queries with no results

Retrieves the statistics of the 1000 most popular queries which returned no results.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"query": "string",
"stats": {"totalCount": 0
}
}
]

Stats of top queries with no results grouped by date

Retrieves the statistics of the 1000 most popular queries which returned no results, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

sortBy	string Default: "totalCount" Enum: "averageClickPosition" "averageOrderValue" "clickThroughRate" "conversionRate" "conversions" "noResultsCount" "revenue" "totalClicks" "totalCount" "totalSuggestionsUsed" "uniqueUsers" Name of the field by which the data will be sorted
ordering	string Default: "desc" Enum: "desc" "asc" Sorting order
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.
searchType	string Default: "full-text-search" Enum: "full-text-search" "autocomplete" "all" Search type for which stats will be retrieved.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/queries-no-results/group/date/top?sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE&searchType=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"query": "string",
"stats": {"totalCount": 0
}
}
]
}
]

Stats of filters

Retrieves the statistics of filters used in searches.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"count": 0,
"filterName": "string"
}
]

Stats of filters grouped by date

Retrieves the statistics of filters used in searches, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"count": 0,
"filterName": "string"
}
]
}
]

Stats of a single filter

Retrieves the statistics of a single filter used in searches.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

filterName

required

string

Name of the filter

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/%7BfilterName%7D/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"count": 0,
"filterValue": "string"
}
]

Stats of a single filter grouped by date

Retrieves the statistics of a single filter used in searches, grouped by days.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

path Parameters

filterName

required

string

Name of the filter

query Parameters

query	string Query for which stats will be returned. If not provided, the results are returned for the most popular queries.
dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/filters/%7BfilterName%7D/group/date/summary?query=SOME_STRING_VALUE&dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"count": 0,
"filterValue": "string"
}
]
}
]

Stats of applied query rules

Retrieve the statistics of applied query rules.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/rules/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"count": 0,
"ruleId": "string"
}
]

Stats of applied query rules grouped by date

Retrieve the statistics of applied query rules, grouped by date.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: SEARCH_STATS_SEARCH_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ASSETS_SEARCH

Authorizations:

JWT

query Parameters

dateFrom	string <date> Lower boundary of the interval for which the statistics will be retrieved. Supports dates up to 90 days before today's date. Defaults to 7 days before current date.
dateTo	string <date> Upper boundary of the interval for which the statistics will be retrieved. Defaults to current date.
index	string Name of the index to use. Defaults to the production index.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/product-search-stats/search-stats/v1/rules/group/date/summary?dateFrom=SOME_STRING_VALUE&dateTo=SOME_STRING_VALUE&index=SOME_STRING_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
500

Content type

application/json

[{"date": "2019-08-24",
"stats": [{"count": 0,
"ruleId": "string"
}
]
}
]

Recommendation campaigns

AI-powered marketing campaigns

Get all recommendation campaigns

Fetch all recommendation campaigns.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_MANY_CAMPAIGN_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

query Parameters

page	integer Default: 0 Page number
limit	integer Default: 50 Maximum number of campaigns on a page
sortBy	string Default: "createdAt" Enum: "createdAt" "updatedAt" "startDate" "endDate" "state" "type" Name of the field by which data will be sorted
ordering	string Default: "desc" Enum: "asc" "desc" Sorting order
includeMeta	boolean Default: false If true, a `meta` JSON block with pagination data is included in the response body. If false, the pagination data is included in the response headers.
type	string Filters the results by campaign type.
state	Array of strings Items Enum: "draft" "active" "paused" Shows only results with states matching this parameter. When this parameter is omitted, all campaigns are returned regardless of state.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/recommendations/v2/campaigns?page=SOME_INTEGER_VALUE&limit=SOME_INTEGER_VALUE&sortBy=SOME_STRING_VALUE&ordering=SOME_STRING_VALUE&includeMeta=SOME_BOOLEAN_VALUE&type=SOME_STRING_VALUE&state=SOME_ARRAY_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404
500

Content type

application/json

{"meta": {"totalPages": 0,
"totalCount": 0,
"page": 0,
"limit": 0,
"sortedBy": "string",
"ordering": "string",
"code": 0,
"link": [{"url": "string",
"rel": "first"
}
]
},
"data": [{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}
],
"extras": {"states": {"active": 0,
"draft": 0,
"paused": 0
}
}
}

Create a recommendation campaign

Create a new recommendation campaign.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_CAMPAIGN_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

Request Body schema: application/json

All the details of a campaign

One of

type required	string Value: "similar" Campaign type
	object Parameters that apply to this campaign
title required	string Campaign title
description	string Campaign description
startDate	string Start date for the campaign
endDate	string End date for the campaign
state	string Enum: "draft" "active" "paused" "deleted" Campaign status
	object Filters that apply to this campaign. If the filters contain an attribute used in the default filters of the recommendation model (Settings > AI Configuration), that default filter is ignored.
itemsCatalogId required	string Only items from this catalog will be recommended.
	Array of objects[ items ] Recommendation slots
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
	Array of objects[ items ] Recommendation boosting strategies
	object The source of item ID or IDs for the recommendation context. This parameter can be passed in all recommendations. In recommendations which don't use item context as part of the recommendation model, the context item can be used only to create filters. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the `itemId` or `itemsSource` parameter when making a request to generate a recommendation from this campaign. The parameter overrides the settings defined here.

Responses

Request samples

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0,
"personalizedBoostingStrength": 0
},
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

Response samples

200
500

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}

Get recommendation campaign details

Retrieve the details of a single campaign.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_SINGLE_CAMPAIGN_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

path Parameters

campaignId

required

string

ID of the campaign

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404
500

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}

Update a recommendation campaign

Update a recommendation campaign by changing the parameters or copying the definition from another campaign.

When you copy from another campaign:

the following campaign data is NOT updated:
- title
- state
- start_date
- end_date
- campaignId
- createdAt
modified_by_user_id changes to the user who performed the update

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_CAMPAIGN_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

path Parameters

campaignId

required

string

ID of the campaign

Request Body schema: application/json

Definition of the updated campaign.

One of

type required	string Value: "similar" Campaign type
	object Parameters that apply to this campaign
campaignId	string Campaign ID
title required	string Campaign title
description	string Campaign description
startDate required	string Start date for the campaign
endDate	string End date for the campaign
createdAt	string Date when the campaign was created
updatedAt	string Date when the campaign was last updated
state required	string Enum: "draft" "active" "paused" "deleted" Campaign status
	object Filters that apply to this campaign. If the filters contain an attribute used in the default filters of the recommendation model (Settings > AI Configuration), that default filter is ignored.
itemsCatalogId required	string Only items from this catalog will be recommended.
additionalResponseAttributes	Array of strings An array of addtional response attributes.
	Array of objects[ items ] Recommendation slots
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
	Array of objects[ items ] Recommendation boosting strategies
	object The source of item ID or IDs for the recommendation context. This parameter can be passed in all recommendations. In recommendations which don't use item context as part of the recommendation model, the context item can be used only to create filters. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the `itemId` or `itemsSource` parameter when making a request to generate a recommendation from this campaign. The parameter overrides the settings defined here.
	object Information whether campaign is part of an a/b test

Responses

Request samples

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}

Response samples

200
404
500

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}

Delete a recommendation campaign

Delete a recommendation campaign. This operation is irreversible.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_CAMPAIGN_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

path Parameters

campaignId

required

string

ID of the campaign

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404
500

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}

Change campaign state

Change the status of a campaign.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_STATE_CAMPAIGN_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

path Parameters

campaignId required	string ID of the campaign
state required	string Enum: "pause" "activate" The new state

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D/state/%7Bstate%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404
500

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}

Copy a recommendation campaign

Copy a campaign. The copied campaign's state will be draft.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_COPY_CAMPAIGN_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

path Parameters

campaignId

required

string

ID of the campaign

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/recommendations/v2/campaigns/%7BcampaignId%7D/copy 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404
500

Content type

application/json

Example

{"type": "similar",
"parameters": {"additionalResponseAttributes": ["string"
],
"boostMetric": "string",
"sortMetric": "string",
"boostMetricStrength": -100,
"shuffleNumItems": 0
},
"campaignId": "string",
"title": "string",
"description": "string",
"startDate": "string",
"endDate": "string",
"createdAt": "string",
"updatedAt": "string",
"state": "draft",
"filterRules": {"excludePurchasedItems": true,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": true,
"elasticExcludePurchasedItemsSinceDays": 0
},
"itemsCatalogId": "string",
"additionalResponseAttributes": ["string"
],
"slots": [{"name": "string",
"itemMin": 0,
"itemMax": 0,
"filterRules": {"filters": "string",
"elasticFilters": "string"
},
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
},
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 0,
"numItems": 0
}
],
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"abTest": {"experimentId": 0,
"variantId": 0,
"status": "NotStarted",
"isBaseline": true
}
}

Get simplified recommendation campaigns

Fetch simplified recommendation campaign data.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_MANY_SIMPLIFIED_CAMPAIGN_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

query Parameters

type	Array of strings Filter by campaign type.
state	Array of strings Items Enum: "draft" "active" "paused" Filter by states.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/recommendations/v2/campaigns/simplified?type=SOME_ARRAY_VALUE&state=SOME_ARRAY_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404
500

Content type

application/json

[{"campaignId": "string",
"title": "string",
"type": "string"
}
]

Recommendations

Personalized item recommendations from the AI engine

Personalized recommendations

Retrieve item recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_PERSONALIZED_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

clientUuid

required

string

Recommendations will be generated for the provided profile UUID.

query Parameters

minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDays	integer Limits the application of the `excludePurchasedItems` filter to a specified number of days.
filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemId	string Item identifier, equal to `itemId` from the item feed. It can be used to define the item context of the query.
itemCatalogId	string Default: "default" Only items from this item feed will be recommended.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Personalized recommendations

Retrieve item recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_PERSONALIZED_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

clientUuid

required

string

Recommendations will be generated for the provided profile UUID.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Section recommendations

Retrieve item recommendations grouped by attribute.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_SECTION_RECOMMENDATIONS_READ

Authorizations:

JWT

path Parameters

clientUuid

required

string

Information will be shown for the provided profile UUID.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
metadataCatalogId	string ID of the catalog which stores attribute metadata
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"metadataCatalogId": "string",
"slots": [{"name": "string",
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"numRows": 1,
"numItems": 1,
"filters": "string",
"elasticFilters": "string"
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"rows": [{"attributeValue": "string",
"itemIds": ["string"
],
"metadata": {"itemId": "string",
"property1": null,
"property2": null
}
}
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Attribute recommendations

Retrieve attribute recommendations.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_ATTRIBUTE_RECOMMENDATIONS_READ

Authorizations:

JWT

path Parameters

clientUuid

required

string

Information will be shown for the provided profile UUID.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
metadataCatalogId	string ID of the catalog which stores attribute metadata
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"metadataCatalogId": "string",
"slots": [{"name": "string",
"attribute": {"name": "string",
"levelRangeModifier": 0
},
"minNumItems": 1,
"maxNumItems": 5,
"filters": "string",
"elasticFilters": "string"
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Last viewed recommendations

Retrieve recent item recommendations seen by a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_LAST_VIEWED_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

clientUuid

required

string

Information will be shown for the provided profile UUID.

query Parameters

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Last viewed recommendations

Retrieve recent item recommendations seen by a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_LAST_VIEWED_RECOMMENDATIONS_READ

Authorizations:

JWT

path Parameters

clientUuid

required

string

Information will be shown for the provided profile UUID.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Recent interactions recommendations

Retrieve recent interactions recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_RECENT_INTERACTIONS_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

clientUuid required	string Information will be shown for the provided profile UUID.
aggregateUUID required	string Information will be shown for the provided aggregate UUID.

query Parameters

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Recent interactions recommendations

Retrieve recent interactions recommendations for a profile.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_RECENT_INTERACTIONS_RECOMMENDATIONS_READ

Authorizations:

JWT

path Parameters

clientUuid required	string Information will be shown for the provided profile UUID.
aggregateUUID required	string Information will be shown for the provided aggregate UUID.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Scoring by metric

Returns items with the highest score of a chosen metric. A list of available metrics can be checked by using this endpoint.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_METRICS_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

query Parameters

sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
itemId	string Item identifier, equal to `itemId` from the item feed. It can be used to define the item context of the query.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDays	integer Limits the application of the `excludePurchasedItems` filter to a specified number of days.
filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogId	string Default: "default" Only items from this item feed will be recommended.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Scoring by metric

Returns items with the highest score of a chosen metric. A list of available metrics can be checked by using this endpoint.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_METRICS_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID required	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric required	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Complementary items for a cart

Show recommendations based on the contents of a cart.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

query Parameters

clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDays	integer Limits the application of the `excludePurchasedItems` filter to a specified number of days.
filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemId	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
itemCatalogId	string Default: "default" Only items from this item feed will be recommended.
boostMetric	string ID of the metric to boost the results by. Metric scores will be combined with recommendation scores, favoring the best-performing results. The list of available metrics can be checked by using this endpoint.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Complementary items for a cart

Show recommendations based on the contents of a cart.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_RECOMMENDATIONS_READ

Authorizations:

JWT

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Complementary items

Returns items complementary to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_PRODUCTS_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

itemId

required

string

Item identifier, equal to itemId from the item feed.

query Parameters

minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDays	integer Limits the application of the `excludePurchasedItems` filter to a specified number of days.
filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogId	string Default: "default" Only items from this item feed will be recommended.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Complementary items

Returns items complementary to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_COMPLEMENTARY_PRODUCTS_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

itemId

required

string

Item identifier, equal to itemId from the item feed.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Similar items

Returns items similar to a given item.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_SIMILAR_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

itemId

required

string

Item identifier, equal to itemId from the item feed.

query Parameters

minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDays	integer Limits the application of the `excludePurchasedItems` filter to a specified number of days.
filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogId	string Default: "default" Only items from this item feed will be recommended.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Similar items

Returns items similar to a given item.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_SIMILAR_RECOMMENDATIONS_READ

Authorizations:

JWT

path Parameters

itemId

required

string

Item identifier, equal to itemId from the item feed.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Visually similar

Returns items visually similar to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_VISUAL_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

itemId

required

string

Item identifier, equal to itemId from the item feed.

query Parameters

minNumItems	integer >= 1 Default: 1 The minimal number of returned item recommendations. If the service is not able to return at least this many recommendations, it will return an error.
maxNumItems	integer <= 100 Default: 5 The maximal number of returned item recommendations.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 250 purchased items are taken into account. Items further back in the purchase history may be included in the recommendation.
excludePurchasedItemsSinceDays	integer Limits the application of the `excludePurchasedItems` filter to a specified number of days.
filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
elastic:filters	string This string defines the criteria that an item must meet in order to be considered for recommendation. The Elastic filter may be dropped if not enough products meet the required criteria. For information on building filters, see "Items Query Language (IQL)" in the Developer Guide.
itemCatalogId	string Default: "default" Only items from this item feed will be recommended.
campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
	object Distinct filters allow you to specify how many recommended items can have the same value of specified attributes.
includeContextItems	boolean The recommendation results will include context items from the request.

Responses

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Visually similar

Returns items visually similar to the given items.

Note: The definition of an item encompasses products, but also articles, images, videos, and any other entities stored in catalogs.

API consumers who can use this method: AI API key (legacy), Web SDK tracker
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: RECOMMENDATIONS_V2_VISUAL_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

itemId

required

string

Item identifier, equal to itemId from the item feed.

Request Body schema: application/json

Definition of the requested recommendation

campaignId	string Default: "defaultCampaign" The campaignId which will be passed as utm_campaign in a link to the recommended item.
campaignName	string The campaign name which will be included in the recommendation.generated event.
catalogId	string Default: "default" Only items from this item feed will be recommended.
clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
contextItemIds	Array of strings Item identifiers, equal to `itemId` from the item feed. They can be used to define the item context of the query.
includeContextItems	boolean Default: false The recommendation results will include context items from the request.
	object Filter configuration
displayAttributes	string Attributes to be returned
	object A/B test context.
keepSlotsOrder	boolean Default: true When `true`, the `data` array in the response is sorted according to slots. Within each slot, the items are sorted by their score (default) or metric (if selected). For example, if you have 3 slots of 2 items each, the first 2 items in `data` are from the first slot, the second 2 are from the second slot, and the last 2 are from the third slot. When `false`, the `data` array in the response is sorted only according to score (default) or metric (if selected). Slots have no effect. The additional `extras.slots` object always shows slots and items as if this setting was `true`. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
personalizeSlotsOrder	boolean Default: false Sort the slots by average personalized slot score. This parameter applies only to personalized and attribute recommendation campaigns. If you want to set `personalizeSlotsOrder` to `true`, `keepSlotsOrder` must also be `true`.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects non-empty [ items ] Slot definitions. To apply default values and fetch all the results as a single slot, send `slots` as an array with one empty object.

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "default",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"abTestContext": {"experimentId": 0,
"variantId": "string",
"requestedCampaignId": "string"
},
"keepSlotsOrder": true,
"personalizeSlotsOrder": false,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 1,
"filters": "string",
"elasticFilters": "string",
"distinctFilter": {"elastic": true,
"filters": [{"field": "string",
"maxNumItems": 0,
"levelRangeModifier": 0
}
]
}
}
]
}

Response samples

200
404
500

Content type

application/json

{"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string"
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}
}
]
},
"data": [{"itemId": "string",
"property1": null,
"property2": null
}
]
}

Get recommendations by campaign

This method allows you to retrieve recommendations based on a campaignID and a context. The context is built based on:

campaign ID (required)
profile UUID
items (for example, items currently in the basket)
item exclusions

This is the recommended and simplest way to fetch recommendations.

Before you use this method, you must to create a recommendations campaign in Synerise. All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_MATERIALIZER_V2_RECOMMEND_CAMPAIGNS_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

path Parameters

campaignID

required

string

Recommendation campaign identifier

query Parameters

clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
itemId	string Item ID or item IDs for the recommendation context. This parameter is: required for similar/complementary items campaigns. optional for personalized campaigns. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. You can repeat this parameter in order to pass a number of context-creating items, for example, in a cart recommendation campaign. This overrides the `itemsSource` settings of the campaign definition. Alternatively, you can pass the `itemsSourceType` and `itemsSourceId` parameters to use context items from source (aggregate or expression). These parameters can't be used at the same request with `itemId`.
itemsSourceType	string Enum: "aggregate" "expression" Item ID or item IDs source type for the recommendation context. Must be used with `itemSourceId`. This overrides the `itemsSource` settings of the campaign definition. In recommendations whose models doesn't use the item context, the attributes of those items can only be used in filters. If the items' source type is 'aggregate', the aggregate result will be used as context items. If the items' source type is 'expression', the expression result will be used as context items. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the `itemId` parameter to define context items directly. Only one of these options is allowed at the same time.
itemsSourceId	string Source of item IDs for the recommendation context. In recommendations whose models doesn't use the item context, the attributes of those items can only be used in filters. Must be used with `itemsSourceType`. If the items' source type is 'aggregate', this is the aggregate's ID. If the items' source type is 'expression', this is the expression's ID. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the `itemId` parameter to define context items directly. Only one of these options is allowed at the same time.
itemIdExcluded	string IDs of items that will be excluded from the generated recommendations. For example, items already added to the basket.
additionalFilters	string Example: additionalFilters=effectivePrice>300 AND effectivePrice<400 IMPORTANT: The `filtersJoiner` attribute is REQUIRED when `additionalFilters` is included. If `filtersJoiner` is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional filters. These are merged with the campaign's own filters according to the logic in `filtersJoiner`. This parameter must include all the additional filters as a single string, for example `additionalFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
filtersJoiner	string Enum: "AND" "OR" "REPLACE" Defines the logic of merging `additionalFilters` with the campaign's existing filters. `REPLACE` replaces the campaign's filters with your filters. `AND` matches if both your filters and the campaign filters are met. `OR` matches if at least one of the filters is met.
additionalElasticFilters	string Example: additionalElasticFilters=effectivePrice>300 AND effectivePrice<400 IMPORTANT: The `elasticFiltersJoiner` attribute is REQUIRED when `additionalElasticFilters` is included. If `elasticFiltersJoiner` is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional elastic filters. These are merged with the campaign's own elastic filters according to the logic in `elasticFiltersJoiner`. This parameter must include all the additional filters as a single string, for example `additionalElasticFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
elasticFiltersJoiner	string Enum: "AND" "OR" "REPLACE" Defines the logic of merging `additionalElasticFilters` with the campaign's existing elastic filters. `REPLACE` replaces the campaign's filters with your filters. `AND` matches if both your filters and the campaign filters are met. `OR` matches if at least one of the filters is met.
displayAttribute	string Item attribute whose value will be returned in the recommendation response. The parameter value will be merged with the configuration of the recommendation. This parameter can be passed multiple times.
includeContextItems	boolean When true, the recommendation response will include context items metadata.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/recommendations/v2/recommend/campaigns/%7BcampaignID%7D?clientUUID=SOME_STRING_VALUE&itemId=SOME_STRING_VALUE&itemsSourceType=SOME_STRING_VALUE&itemsSourceId=SOME_STRING_VALUE&itemIdExcluded=SOME_STRING_VALUE&additionalFilters=SOME_STRING_VALUE&filtersJoiner=SOME_STRING_VALUE&additionalElasticFilters=SOME_STRING_VALUE&elasticFiltersJoiner=SOME_STRING_VALUE&displayAttribute=SOME_STRING_VALUE&includeContextItems=SOME_BOOLEAN_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404
500

Content type

application/json

{"data": [{"itemId": "string"
}
],
"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string",
"property1": null,
"property2": null
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"status": 0,
"error": "string",
"message": "string"
}
}
]
}
}

Get recommendations by campaign

This method allows you to retrieve recommendations based on a campaignID and a context. The context is built based on:

campaign ID (required)
profile UUID
items (for example, items currently in the basket)
item exclusions

This is the recommended and simplest way to fetch recommendations.

Before you use this method, you must to create a recommendations campaign in Synerise. All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.

API consumers who can use this method: AI API key (legacy), Web SDK tracker, Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_MATERIALIZER_V2_RECOMMEND_CAMPAIGNS_RECOMMENDATIONS_READ

Authorizations:

TrackerKey

JWT

Request Body schema: application/json

clientUUID	string Profile UUID. This parameter is required for these recommendation types: Personalized Last seen Recent interactions Section Attribute This parameter can be passed in all recommendations. In recommendations which don't require the customer context, it can still be used to create filters.
campaignId required	string Campaign ID for establishing the context
items	Array of strings An array of item identifiers (`itemId` in the item feed) for the context. This could be, for example, the current basket, or the item that is currently being viewed. This overrides the `itemsSource` settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. Alternatively, you can use the `itemsSource` object to get item IDs from an aggregate or expression. `items` and `itemsSource` can't be used at the same time.
	object Source of the Item ID or item IDs for the recommendation context. This overrides the `itemsSource` settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the `itemId` parameter to define context items directly. Only one of these options is allowed at the same time.
itemsExcluded	Array of strings >= 0 items Items (identified by `itemId` in the item feed) that will be excluded from the generated recommendations. For example, items already added to the basket.
additionalFilters	string IMPORTANT: The `filtersJoiner` attribute is REQUIRED when `additionalFilters` is included. If `filtersJoiner` is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional filters. These are merged with the campaign's own filters according to the logic in `filtersJoiner`. This parameter must include all the additional filters as a single string, for example `additionalFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
filtersJoiner	string Enum: "AND" "OR" "REPLACE" Defines the logic of merging `additionalFilters` with the campaign's existing filters. `REPLACE` replaces the campaign's filters with your filters. `AND` matches if both your filters and the campaign filters are met. `OR` matches if at least one of the filters is met.
additionalElasticFilters	string IMPORTANT: The `elasticFiltersJoiner` attribute is REQUIRED when `additionalElasticFilters` is included. If `elasticFiltersJoiner` is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional elastic filters. These are merged with the campaign's own elastic filters according to the logic in `elasticFiltersJoiner`. This parameter must include all the additional filters as a single string, for example `additionalElasticFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
elasticFiltersJoiner	string Enum: "AND" "OR" "REPLACE" Defines the logic of merging `additionalElasticFilters` with the campaign's existing elastic filters. `REPLACE` replaces the campaign's filters with your filters. `AND` matches if both your filters and the campaign filters are met. `OR` matches if at least one of the filters is met.
displayAttributes	Array of strings >= 0 items An array of item attributes which value will be returned in a recommendation response. The array will be merged together with the configuration of the recommendation.
includeContextItems	boolean When true, the recommendation response will include context items metadata.

Responses

Request samples

Content type

application/json

{"clientUUID": "string",
"campaignId": "string",
"items": ["string"
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"itemsExcluded": ["string"
],
"additionalFilters": "effectivePrice>300 AND effectivePrice<400",
"filtersJoiner": "AND",
"additionalElasticFilters": "effectivePrice>300 AND effectivePrice<400",
"elasticFiltersJoiner": "AND",
"displayAttributes": ["string"
],
"includeContextItems": true
}

Response samples

200
404
500

Content type

application/json

{"data": [{"itemId": "string"
}
],
"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string",
"property1": null,
"property2": null
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"status": 0,
"error": "string",
"message": "string"
}
}
]
}
}

Get recommendations by campaign and profile identifier

Before you use this method: you must create a recommendations campaign in Synerise. All the recommendation filters and parameters will be handled for you automatically according to a campaign's configuration.

The method allows you to retrieve recommendations based on a campaignID, profile's identifier name (the value of the identifier is provided in the request body), and a context. The context is built based on:

campaign ID (required)
identifierName (required)
identifierValue (required)
items (for example, items currently in the basket)
item exclusions

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: API_MATERIALIZER_V2_RECOMMEND_WITH_CUSTOM_ID_RECOMMENDATIONS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

path Parameters

campaignID required	string Recommendation campaign identifier
identifierName required	string Enum: "id" "uuid" "email" "custom_identify" The name of the profile identifier to use for the request. By default, the allowed identifier types are `id`, `uuid`, `email`, and `custom_identify`. This may be changed in the workspace configuration.

Request Body schema: application/json

identifierValue required	string Value of the identifier selected in the path attributes
items	Array of strings An array of item identifiers (`itemId` in the item feed) for the context. This could be, for example, the current basket, or the item that is currently being viewed. This overrides the `itemsSource` settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. Alternatively, you can use the `itemsSource` object to get item IDs from an aggregate or expression. `items` and `itemsSource` can't be used at the same time.
	object Source of the Item ID or item IDs for the recommendation context. This overrides the `itemsSource` settings of the campaign definition. This parameter can be passed in all recommendations. In recommendations which don't use the context item as part of the recommendation model, the context item can only be used to create filters. The item ID source (aggregate or expression) should return a string or an array of strings. If it returns numerical values, the recommendations engine attempts to convert them into strings while processing the request. Alternatively, you can pass the `itemId` parameter to define context items directly. Only one of these options is allowed at the same time.
itemsExcluded	Array of strings >= 0 items Items (identified by `itemId` in the item feed) that will be excluded from the generated recommendations. For example, items already added to the basket.
additionalFilters	string IMPORTANT: The `filtersJoiner` attribute is REQUIRED when `additionalFilters` is included. If `filtersJoiner` is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional filters. These are merged with the campaign's own filters according to the logic in `filtersJoiner`. This parameter must include all the additional filters as a single string, for example `additionalFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
filtersJoiner	string Enum: "AND" "OR" "REPLACE" Defines the logic of merging `additionalFilters` with the campaign's existing filters. `REPLACE` replaces the campaign's filters with your filters. `AND` matches if both your filters and the campaign filters are met. `OR` matches if at least one of the filters is met.
additionalElasticFilters	string IMPORTANT: The `elasticFiltersJoiner` attribute is REQUIRED when `additionalElasticFilters` is included. If `elasticFiltersJoiner` is missing, the additional filters do not work. Do NOT send multiple instances of this parameter. Additional elastic filters. These are merged with the campaign's own elastic filters according to the logic in `elasticFiltersJoiner`. This parameter must include all the additional filters as a single string, for example `additionalElasticFilters=effectivePrice>300 AND effectivePrice<400` (the spaces are required).
elasticFiltersJoiner	string Enum: "AND" "OR" "REPLACE" Defines the logic of merging `additionalElasticFilters` with the campaign's existing elastic filters. `REPLACE` replaces the campaign's filters with your filters. `AND` matches if both your filters and the campaign filters are met. `OR` matches if at least one of the filters is met.
displayAttributes	Array of strings >= 0 items An array of item attributes which value will be returned in a recommendation response. The array will be merged together with the configuration of the recommendation.
includeContextItems	boolean When true, the recommendation response will include context items metadata.

Responses

Request samples

Content type

application/json

{"identifierValue": "string",
"items": ["string"
],
"itemsSource": {"type": "aggregate",
"id": "string"
},
"itemsExcluded": ["string"
],
"additionalFilters": "effectivePrice>300 AND effectivePrice<400",
"filtersJoiner": "AND",
"additionalElasticFilters": "effectivePrice>300 AND effectivePrice<400",
"elasticFiltersJoiner": "AND",
"displayAttributes": ["string"
],
"includeContextItems": true
}

Response samples

200
404
500

Content type

application/json

{"data": [{"itemId": "string"
}
],
"extras": {"correlationId": "string",
"contextItems": [{"itemId": "string",
"property1": null,
"property2": null
}
],
"slots": [{"id": 0,
"name": "string",
"itemIds": ["string"
],
"error": {"status": 0,
"error": "string",
"message": "string"
}
}
]
}
}

Time Optimizer

Predict when a Profile is likely to be active

Generate activity time predictions

Calculate the probability of a profile performing an activity (event) at specific times of the week.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: AI_TIME_OPTIMIZER_GET_PREDICTIONS_ANALYTICS_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: ANALYTICS_AI_TIME_OPTIMIZER

Authorizations:

JWT

Request Body schema: application/json

One of

clientID required	Array of strings <= 1000 items An array of profile IDs. To generate predictions for fake profiles, send empty strings as the identifiers.
mode	string Default: "standard" The mode name
	Array of Array of Hour range (integers) or Hour (integer) <= 168 items [ items ] An array of times and time ranges to include in the predictions. If empty or omitted, the entire week is included (with the exceptions listed in `timeIndexExclude`, if they exist). A time range is a two-item array. For example, `[4,7]` is the range from Monday, 03:00 to Monday, 06:59. You can mix hours and time ranges in the request.
	Array of Array of Hour range (integers) or Hour (integer) <= 168 items [ items ] An array of times and time ranges to exclude from the predictions. If empty or omitted, the entire week is included (according to the time selections made in `timeIndex`, if they exist). A time range is a two-item array. For example, `[4,7]` is the range from Monday, 03:00 to Monday, 06:59. You can mix hours and time ranges in the request.
topN	integer [ 1 .. 168 ] The number of best predictions to return for each profile. If omitted, predictions for every hour of the week are returned.

Responses

Request samples

Content type

application/json

Example

{"clientID": ["67346"
],
"mode": "standard",
"timeIndex": [[0,
23
],
24,
25,
26,
[27,
48
]
],
"timeIndexExclude": [[0,
23
],
24,
25,
26
],
"topN": 1
}

Response samples

200

Content type

application/json

Example

{"clientID": ["67346"
],
"hours": [16,
32,
64
],
"predictions": [0.013318098150193691,
0.012947574257850647,
0.0123398806899786
]
}

Test Optimizer

Experiments with A/B or multivariate tests

Get allocation algorithms

Provide a dictionary of algorithms available for use in experiment creation.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/optimizer-manager/v1/dictionaries/allocation-algorithms 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

["ThompsonSampling"
]

Find predefined goals

Find predefined goals that exist in Synerise by default.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/optimizer-manager/v1/goals 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"goalId": 0,
"name": "string",
"field": "string",
"isPredefined": true,
"winningDirection": "Increase",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z"
}
]

Delete predefined goal

Delete a predefined goal.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the goal

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/optimizer-manager/v1/goals/%7Bid%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

404

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Find basic experiments

Find basic experiments. You can filter the results by campaign type.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

query Parameters

campaignType	string CampaignType of the experiment
status	Array of strings Requested status of the experiment. One of: NotStarted, Running, Paused, Finished. May pass more than one status.

Responses

Request samples

curl --request GET 
  --url 'https://api.synerise.com/optimizer-manager/v1/experiments?campaignType=SOME_STRING_VALUE&status=SOME_ARRAY_VALUE' 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"experimentId": 0,
"name": "string",
"author": 0,
"description": "string",
"campaignType": "string",
"experimentType": "AB",
"variantsSelectionAlgorithm": "ThompsonSampling",
"variantsAllocationMethod": "Manual",
"status": "NotStarted",
"startedAt": "2019-08-24T14:15:22Z",
"stoppedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"variants": [{"variantId": 0,
"name": "string",
"description": "string",
"weight": 0,
"metadata": "string",
"isControlGroup": true,
"isBaseline": true
}
]
}
]

Create experiment

Create a new experiment.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_CREATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

Request Body schema: application/json

name required	string Experiment name
description	string Experiment description
campaignType	string Campaign type that the experiment relates to
experimentType required	string Enum: "AB" "Multivariant" The type of the experiment
variantsAllocationMethod required	string Enum: "Manual" "Automatic" The variant allocation method - manual or performed by the AI engine
required	Array of objects[ items ] An array of experiment variants
required	Array of objects[ items ] An array of experiment goals

Responses

Request samples

Content type

application/json

{"name": "string",
"description": "string",
"campaignType": "string",
"experimentType": "AB",
"variantsAllocationMethod": "Manual",
"variants": [{"name": "string",
"description": "string",
"weight": 0,
"metadata": "string",
"isControlGroup": true,
"isBaseline": true
}
],
"goals": [{"goalId": 0,
"name": "string",
"field": "string",
"isPredefined": true,
"winningDirection": "Increase",
"eventTriggerBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
},
"eventFilterBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
}
}
]
}

Response samples

400

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Calculate sample size

Calculate the sample size for a variant.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

Request Body schema: application/json

baselineConversionRate required	number [ 0 .. 100 ] The initial conversion rate required for a customer to be included in the variant's customer group
minimumDetectableEffect required	number [ 0 .. 100 ] The minimum change in CTR that is detected
statisticalSignificance required	number [ 0 .. 100 ] Statistical significance is the probability that a change between the baseline CTR and the variation is not random. In other words, this the risk tolerance and how confident you are about the results - a statistical significance of 90% means that you consider a 10% probability that the results are wrong and misleading.

Responses

Request samples

Content type

application/json

{"baselineConversionRate": 100,
"minimumDetectableEffect": 100,
"statisticalSignificance": 100
}

Response samples

200
400

Content type

application/json

{"sampleSize": 0
}

Get experiment

Retrieve the details of an experiment.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200
404

Content type

application/json

{"experimentId": 0,
"name": "string",
"author": 0,
"description": "string",
"campaignType": "string",
"experimentType": "AB",
"variantsSelectionAlgorithm": "ThompsonSampling",
"variantsAllocationMethod": "Manual",
"status": "NotStarted",
"startedAt": "2019-08-24T14:15:22Z",
"stoppedAt": "2019-08-24T14:15:22Z",
"createdAt": "2019-08-24T14:15:22Z",
"updatedAt": "2019-08-24T14:15:22Z",
"variants": [{"variantId": 0,
"name": "string",
"description": "string",
"weight": 0,
"metadata": "string",
"isControlGroup": true,
"isBaseline": true
}
],
"goals": [{"goalId": 0,
"name": "string",
"field": "string",
"isPredefined": true,
"winningDirection": "Increase",
"eventTriggerBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
},
"eventFilterBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
}
}
]
}

Update experiment

Update an existing experiment.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_UPDATE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Request Body schema: application/json

name required	string Experiment name
description	string Experiment description
campaignType	string Campaign type that the experiment relates to
experimentType required	string Enum: "AB" "Multivariant" The type of the experiment
variantsAllocationMethod required	string Enum: "Manual" "Automatic" The variant allocation method - manual or performed by the AI engine
required	Array of objects[ items ] An array of experiment variants
required	Array of objects[ items ] An array of experiment goals

Responses

Request samples

Content type

application/json

{"name": "string",
"description": "string",
"campaignType": "string",
"experimentType": "AB",
"variantsAllocationMethod": "Manual",
"variants": [{"name": "string",
"description": "string",
"weight": 0,
"metadata": "string",
"isControlGroup": true,
"isBaseline": true
}
],
"goals": [{"goalId": 0,
"name": "string",
"field": "string",
"isPredefined": true,
"winningDirection": "Increase",
"eventTriggerBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
},
"eventFilterBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
}
}
]
}

Response samples

400
404

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Delete experiment

Delete an experiment permanently.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_DELETE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request DELETE 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

404

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Get experiment goals

Find the goals of an experiment.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D/goals 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"goalId": 0,
"name": "string",
"field": "string",
"isPredefined": true,
"winningDirection": "Increase",
"eventTriggerBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
},
"eventFilterBody": {"action": {"id": 123,
"name": "dynamicContent.show"
},
"expressions": [{"attribute": {"id": 1245435,
"param": "id",
"type": "PARAM"
},
"constraint": {"logic": "EQUAL",
"type": "STRING_ONE",
"value": {"constant": "campaign-7574",
"type": "CONSTANT"
}
}
}
]
}
}
]

Get experiment variants

Find the variants of an experiment.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request GET 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D/variants 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

200

Content type

application/json

[{"variantId": 0,
"name": "string",
"description": "string",
"weight": 0,
"metadata": "string",
"isControlGroup": true,
"isBaseline": true
}
]

Start experiment

Start an experiment (for paused experiments, use this method).

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D/start 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

400
404

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Stop experiment

Stop an experiment. It cannot be started again.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D/stop 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

400
404

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Pause experiment

Pause an experiment. It can be resumed later.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D/pause 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

400
404

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Resume experiment

Resume an experiment after it was paused.

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_MANAGER_TESTOPTIMIZER_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Responses

Request samples

curl --request POST 
  --url https://api.synerise.com/optimizer-manager/v1/experiments/%7Bid%7D/resume 
  --header 'Authorization: Bearer _YOUR_JWT_TOKEN_'

Response samples

400
404

Content type

application/json

{"path": "string",
"timestamp": "2019-08-24T14:15:22Z",
"errorCode": "string",
"status": 0,
"message": "string",
"traceId": "string"
}

Find the best variant

Run statistical test to find the best variant in A/B/n test

API consumers who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_ANALYTICS_TESTOPTIMIZER_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

Request Body schema: application/json

binary required	boolean
required	Array of objects[ items ]
confidence	number

Responses

Request samples

Content type

application/json

{"binary": true,
"variants": [{"samples": 0,
"positiveSamples": 0,
"mean": 0,
"variance": 0,
"squaresMean": 0
}
],
"confidence": 0
}

Response samples

200

Content type

application/json

{"winner": 0,
"isWinner": [true
]
}

Choose experiment variant

Request a variant to be used in an experiment for a customer. The variant is chosen by the AI engine.

API consumer who can use this method: Workspace (formerly Business Profile)
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: OPTIMIZER_ANALYTICS_TESTOPTIMIZER_EXECUTE
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_TEST_OPTIMIZER

Authorizations:

JWT

path Parameters

id

required

integer

ID of the experiment

Request Body schema: application/json

clientUUID

required

string

UUID of the profile

Responses

Request samples

Content type

application/json

{"clientUUID": "string"
}

Response samples

200
400

Content type

application/json

{"experimentId": 0,
"variantId": 0,
"variantName": "string"
}

Item filters

Validate and test item filters

Validate item filter

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 who can use this method: Workspace (formerly Business Profile), Synerise User
API key Permissions are assigned to API keys (for Profile and Workspace scopes) and dictate which operations are available when using a particular API key. In the application, you can manage those permissions in Settings > API Keys. Remember that Profile and Workspace API keys are separate entities.permission required: ITEMS_FILTER_VALIDATE_READ
User permissions are grouped and assigned to user roles. For each group, you can set separate permissions for the following operations: read, execute, create, edit, delete. In the application, they are available in Settings > Roles. To edit a role's permissions, hover over the role and click the "Permissions" button.User role permission group which allows access to this method: CAMPAIGNS_RECOMMENDATIONS

Authorizations:

JWT

query Parameters

itemsCatalogId	string Default: "default" 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.
exampleItems	integer Default: 10 Controls how many example items will be returned

Request Body schema: application/json

filteringString required	string IQL filtering expression
clientUUID	string UUID of the profile which creates the profile context
contextItems	Array of strings itemIds of the items which create the item context
candidateItems	Array of strings 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.

Responses

Request samples

Payload

Content type

application/json

{"filteringString": "IF(\"abcd\" IN client.tags,discount == 0,discount > 0)",
"clientUUID": "68df2317-0edb-4cc9-8b39-5ab68325f891",
"contextItems": ["12345"
],
"candidateItems": ["67890"
]
}

Response samples

200
400
500
502

Content type

application/json

{"filteringString": "IF(\"abcd\" IN client.tags,discount == 0,discount > 0)",
"contextItems": ["12345"
],
"clientUUID": "68df2317-0edb-4cc9-8b39-5ab68325f891",
"parserResult": {"valid": true,
"message": "string",
"parsedFilteringString": "string"
},
"evaluationResult": {"resultSize": 0,
"modifiedFilteringString": "string",
"evaluationErrors": [{"filter": "string",
"message": "string"
}
]
},
"extracts": {"clientExtracts": {"attributeConstants": ["string"
],
"segmentationsConstant": ["string"
],
"aggregateConstants": ["string"
],
"expressionConstants": ["string"
],
"TagsConstant": true
},
"contextConstants": ["string"
],
"variables": ["string"
]
},
"candidateItems": [{"itemId": "67890",
"valid": true
}
],
"exampleItems": ["string"
]
}