Recommendation API requests

You can make requests for:

results of a campaign created in the Synerise Portal.
With this option, you can create a campaign with filters instead of defining them for each request. You can still tweak filters when making the request. This is the most commonly used method.
recommendations served by a recommendation model without creating a campaign.
With this option, you can make requests without preparing a campaign first, but you need to send the settings that are normally part of the campaign.

Before you begin

Ensure that the model for the type of recommendations you want to request is enabled in the settings of an item feed.
You should be familiar with recommendation types and filter types:
- Recommendation types
- Recommendation filter types

Elements of the request

Context

Each recommendation is made in context of a Profile. The profile’s attributes can be used in filters.

Tip: When making requests from a website, you can find the profile’s UUID in the _snrs_uuid cookie.

You can also add item context to your requests, for example when generating complementary purchase recommendations for a product. The context item’s attributes can be used in filters.
In some recommendations, the item context is required. When it’s not required, it can still be included in order to use the context item’s attributes in filters.

Address

The domain of the recommendations API depends on your workspace.

If your workspace is hosted on the Azure server, the base URL is https://api.synerise.com/
If your workspace is hosted on the Google Cloud Server, the base URL is https://api.geb.synerise.com/
If you have a custom tracking domain configured, use the custom domain (only for requests made from sites which have a Tracking Code).

Important: With the custom tracking domain, you must add /ai before the endpoint path in addition to changing the domain.

Authentication

The requests can be authenticated in the following ways:

Recommended method: With the key from your tracking code. This tracker key is added to the request in the token query parameter.
This method is used in most examples in this guide.
With a Workspace JWT (Bearer auth) or Basic authentication.

WARNING: Workspace JWTs and Basic Authentication can be used ONLY FOR SERVER-TO-SERVER communication. DO NOT use them in your mobile applications or websites.

The following examples show the two methods of authentication.

This is the recommended method. The tracker key is included in the token parameter.

curl --location 'https://api.synerise.com/recommendations/v2/recommend/campaigns/DkhvrZoTKthD?token=98A5FC55-0000-0000-0000-98339BDECAE6&clientUUID=cf9e9b57-7776-51bc-b7bc-75cc75abdf59'
                                                                                              <-------------- tracker key ------------->

where:

DkhvrZoTKthD is an example campaign ID
98A5FC55-0000-0000-0000-98339BDECAE6 is an example tracker key
cf9e9b57-7776-51bc-b7bc-75cc75abdf59 is an example profile UUID

Making a request

Campaign results

You can use two HTTP methods:

GET: elements of the query are passed as query parameters. This method is recommended for making requests from a website.
POST: elements of the query are passed in the request body.

Tip:

For details of all the parameters available for these endpoints, see the API Reference:

GET
POST

Examples:

In GET requests, the item context is sent in the itemId attribute. In campaigns which accept multiple items in the context (cart recommendations), send the attribute multiple times. See example:

curl --location 'https://api.synerise.com/recommendations/v2/recommend/campaigns/DkhvrZoTKthD?itemId=0196499479257&itemId=0000301448594&itemId=0000301826378&token=98A5FC55-0000-0000-0000-98339BDECAE6&clientUUID=cf9e9b57-7776-51bc-b7bc-75cc75abdf59'

where:

DkhvrZoTKthD is an example campaign ID
itemId=0196499479257&itemId=0000301448594&itemId=0000301826378 are 3 example items for context.
The itemId parameter must be sent multiple times to include multiple items.
If the campaign doesn’t require an item context and you don’t want to use it in filters, skip the itemId parameter entirely.
98A5FC55-0000-0000-0000-98339BDECAE6 is an example tracker key
cf9e9b57-7776-51bc-b7bc-75cc75abdf59 is an example profile UUID

Requests to a model

Instead of getting the results of a recommendation campaign, you can make ad-hoc requests to recommendation models.

In this case, each model has separate endpoints (see API Reference for a list).

Note:

In these requests, you can pass a campaignId parameter. This parameter is added as utm_campaign to the links in the recommendation response for use in Analytics. It doesn’t need to point to any existing recommendation campaign.
Some recommendation types require additional information, for example the “Recent interactions” model needs an aggregate that defines the interactions to take into account. For details, see the API reference of a particular recommendation type.

Examples:

This request fetches a personalized recommendation without any item context or filters.

curl --location 'https://api.synerise.com/recommendations/v2/recommend/items/users/cf9e9b57-7776-51bc-b7bc-75cc75abdf59?token=98A5FC55-0000-0000-0000-98339BDECAE6'

where:

cf9e9b57-7776-51bc-b7bc-75cc75abdf59 is an example profile UUID
98A5FC55-0000-0000-0000-98339BDECAE6 is an example tracker key

For more details, see API Reference

Learn more

A comprehensive list of all endpoints, settings, and parameters is available in the API Reference.

Recommendation API requests

Before you begin

Elements of the request

Context

Address

Authentication

Making a request

Campaign results

Requests to a model

Learn more

We are sorry to hear that

Awesome!