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

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.

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.
    You can also refer to a campaign by its slug.
  • 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:

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.
    You can also refer to a campaign by its slug.
  • 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.

😕

We are sorry to hear that

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

😉

Awesome!

Thank you for helping improve out documentation. If you need help or have any questions, please consider contacting support.

Close modal icon Placeholder alt for modal to satisfy link checker