AI Recommendations (Apr 12, 2024 8:16:00 AM)

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

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 API key

Responses

Request samples

Content type

application/json

{"apiKey": "string"
}

Response samples

200
401

Content type

application/json

{"token": "eyJhbGciOiinvalidI6IkFQSSIsInJsbSI6ImNsaWVudCIsImN0ZCI6MTUyODM1NTgzMjEzOCwiZW1sIjoia3J6eXN6dG9mLmN6ZXJlcGFrQGdtYWlsLmNvbSIsImlzcyI6IlN5bmVyaXNlIiwiYnBpIjo1OTQsImNsSWQiOjUyNTQ0NjU3NCwinvalidx2XwJp-QBZ94d_EEKf41KtDCE33KhP_vTAYrs-JzbnIHgKRvG6ZRwsNOL8OTnbfbUZH4XYaqBB_tZTPPKfzHutP6GEGp7PLtu2E92JbChkVyrn8VCQ5v4z2e1-zsdgbmWcQk2g9RydaydO6NYO55suT3Hz2ZRv0AYLsG8rM1biZGdREWx9OaknVVuIo2ivehBiukL7VQ6Bu8ugjep3mn-z666a-nCMh6ZuASiQ6Geq0NSWmdDQIoCa5Hg44KzMfGRlCR2uKBXeHTD0SkwJ1VJM0sHNKwSfMXKpaX8OJ5wUJpgCzDzQwKVgxgWFp4eO_sbcvxWrpI7W0lfdCy1WKirnZ6Uh3uJ06v97GQDAQqVgBZFEpS47MrGZhTNuAG4ZbfYO7yyxVO8AHQbEC-UvZ-8DC1XZjvQ6S1uNqQIlVGcthnrxg8K6vKVhNzu6ifQI0bbsCl8bGsKkXOEK1pKR3ekckcSjNeeY2LrcdXs8F2gtkm0TjXU"
}

Authenticate as Profile

Obtain a new JWT token 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 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://help.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. 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.

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": { },
"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 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://help.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. 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.

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": { },
"tags": ["string"
]
}

Response samples

Content type

application/json

{"conditions": ["string"
],
"status": "SUCCESS",
"token": "string"
}

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	string Profile API key (same as for Profile login)
deviceId	string Unique Android or iOS device ID
uuid	string UUID of the Profile. It is a unique identifier.

Responses

Request samples

Content type

application/json

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

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"
}

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

Value: "TOTP_AUTHENTICATOR"

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

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

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

Responses

Request samples

Content type

application/json

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

Response samples

200
400
401

Content type

application/json

{"token": "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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}
],
"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 Keep slots order
	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,
"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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

Update a recommendation campaign

Update a 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_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 Keep slots order
	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
},
"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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

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,
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"itemsSource": {"type": "aggregate",
"id": "string"
}
}

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

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 (required)
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 required	string Profile UUID
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 required	string Profile UUID for establishing the context
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

This is the recommended and simplest way to fetch recommendations.

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"
}
}
]
}
}

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 100 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 catalog will be recommended.
	object Distinct filter allows 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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
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": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
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": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "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 filter allows 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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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 filter allows 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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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 under 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 under 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 required	string UUID of the profile for which the results are being retrieved.
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 100 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 catalog will be recommended.
	object Distinct filter allows 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 under 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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric required	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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 basket

Show recommendations based on the contents of a basket.

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 required	string UUID of the profile for which the results are being retrieved.
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 100 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 catalog 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 under by using this endpoint.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Distinct filter allows 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 basket

Show recommendations based on the contents of a basket.

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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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 required	string UUID of the profile for which the results are being retrieved.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 100 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 catalog will be recommended.
	object Distinct filter allows 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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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 required	string UUID of the profile for which the results are being retrieved.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 100 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 catalog will be recommended.
	object Distinct filter allows 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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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 required	string UUID of the profile for which the results are being retrieved.
excludePurchasedItems	boolean Default: false When true, the recommendation results will include only items that the profile hasn't purchased before. IMPORTANT: Only the last 100 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 catalog 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 filter allows 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 Only items from this catalog will be recommended.
clientUUID required	string UUID of the profile for which the results are being retrieved.
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
keepSlotsOrder	boolean Default: true When FALSE, the order of the slots is decided by the AI engine. When TRUE, they are ordered according to how they were sent in the request.
sortMetric	string ID of the metric to sort the results by. The list of available metrics can be checked under by using this endpoint.
	object Result boosting parameters
	Array of objects[ items ] Boosting strategies
required	Array of objects[ items ] Slots data

Responses

Request samples

Content type

application/json

{"campaignId": "defaultCampaign",
"campaignName": "string",
"catalogId": "string",
"clientUUID": "string",
"contextItemIds": ["string"
],
"includeContextItems": false,
"filterRules": {"excludePurchasedItems": false,
"excludePurchasedItemsSinceDays": 0,
"elasticExcludePurchasedItems": false,
"elasticExcludePurchasedItemsSinceDays": 0
},
"displayAttributes": "string",
"keepSlotsOrder": true,
"sortMetric": "string",
"boostingParameters": {"metric": "string",
"strength": 0,
"personalizedBoostingStrength": 0
},
"boostingStrategies": [{"name": "string",
"condition": "string",
"strength": 1
}
],
"slots": [{"name": "string",
"minNumItems": 1,
"maxNumItems": 5,
"shuffleNumItems": 0,
"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
}
]
}