The Recommendation API gives you direct access to Recommendations.

This is intended for backend usage to expose your data if used from a frontend implementation.

There are 2 parts linked to the integration of Recommendations:

1. Interaction tracking
2. Requesting recommendations

By enabling the Recommendations module, you can leverage the automatic installation of the Recommendations tracking JS script, via the SITE JS script tag.

The Recommendations JS tag will collect relevant interactions of users with the customer website like: page views, clicks, add-to-carts, ... The interactions are the most valuable information for the algorithms in Recommendations recommendation engine. These interactions are captured automatically.

For requesting and showing recommendations, Recommendations provides an integration for the web which consist out of three principal options:

1. By using the HTML Widgets provided by Recommendations
2. By an implementation via the Recommendations Javascript SDK
3. By fetching JSON recommendations via the Recommendations REST API

This documentation focuses on the Recommendations REST API, for more information on the other implementations reach out to your Marigold Engage contact.

Recommendations uses a wide range of information to make recommendations. The AI engine can make personalised recommendations but to be able to do this, it is required to properly identify the user.

The user identities & identification are provided by Marigold Engage SITE product. You cannot use your own customer identifiers when requesting personalised recommendations from Recommendations, but you can use the Site profile identifiers when communicating with Recommendations.

To be able to request personalised recommendations, follow this 2-step process:

1. Request the Site profile for a User
2. Request Recommendations recommendations for the Site profile

A typical situation is when you have an internal user reference. In the example below, we will use a "user_ID" with reference 99999.

By doing a Site profile lookup, you can get the Marigold Engage profile reference back. The step below uses the API to lookup a Site profile. All the details for the Site endpoint can be found under the Site Identifcation section.

POST https://site-azp.slgnt.eu/frontend/api/track

with the following JSON properties in the request body:

{
    "universeId": "123e4567-e89b-12d3-a456-426614174000",
    "customIdentifier": "99999",
    "referer": "https://www.google.be/",
    "isEvent": true,
    "isIdentificationRequest": true,
    "isTargeting": false
}

Important to know are the properties:

• universeId : refers to your instance setup for Site, which is can found in the Site configuration.
• customIdentifier : refers to the internal user reference, which would be the "user_ID" 12345 from example

The response body would contain the following information:

{
    "profileId": "123ABCD45678iY2Q0LWJhNGE4NjFkNzFkMDNmI3MjdjNzYtMWQ2ZC00NTZkL",
    "profileInfo": { },
    "doNotTrack": false,
    "$$profileId": "abc12345-ae74-a40ad",
    "$$thirdPartyId": "a123456789"
}

From the Site profile response, you need to extract the $$profileId and the $$thirdPartyId. By passing these properties you can request Recommendations to return personalised recommendations.

In the recommendations API you can pass the Site profile properties, by mapping the sid & tpid.

GET https://offer.slgnt.eu/api/abc123456/r?widgetid=demo&sid=abc12345-ae74-a40ad&tpid=a123456789&lang=nl&loc=be

• $$thirdPartyId is mapped to the Marigold Engage system ID of the contact tpid (Required)
• $$profileId is mapped to the Site profile ID reference sid (Optional)

All the options and properties for the Recommendations recommendations endpoints can be found under the Smart Content Recommendations Identifcation section.

The Recommendation API can be reached from multiple domains, each specific to a region. You should use the domain that matches the region where your data is stored and processed. You can use one of the following domains:

• Europe: https://offer.slgnt.eu
• United States: https://offer.slgnt.us

Structure:

https://domain/api/{customer}/operation?params

Example:

https://offer.slgnt.eu/api/abc123456/r?widgetid=demo&lang=nl&loc=be

Definition:

0. Part 0: domain - The base url is a reference to your regional domain.
1. Part 1: api - Refers to the API feature of the Recommendations product
2. Part 2: customer - Refers to the unique identifier for a customer.
3. Part 3: operation - Refers to Recommendations operations.
4. Part 4: params - Refers to specific input parameters to instruct the operation.

The API is publicly available without credentials. By passing the accept-format you can define the content negotiation and the Recommendations engine will respond in the desired format.

When the accept-format is not passed along, the API will respond with in the HTML format.

Supported content negotiation:

• accept: application/json Responds with the data in JSON format
• accept: application/html Responds with the data in HTML format

Response Format

The response format will respect the accept-format to respond the data in the requested format.

Whether a request succeeded is indicated by the HTTP status code. A 2xx status code indicates success, whereas a 4xx or 5xx status code indicates failure.

When a request fails, the response body is still JSON, but always contains the field message which you can inspect for debugging purposes.

Response properties

The response will contain a set of fixed properties (see endpoint documentation), which can be extended by any field that is available in the catalog.

By marking the "This field will be sent with the API responses as", this field will be included in the JSON response as a property of the recommendation item object.

It is even possible to specify a custom property name, like in the example below, where the catalog field PRODUCT will be returned as the property TITLE .

Versioning

The Recommendations API is versioned to allow versions with new functionality or changes be released without impact of existing implementations.

When we make improvements to the current version of the API endpoints, we strive to make only backwards-incompatible changes. We release regularly improvements or new endpoints. Read our API changelog to stay up-to-date with the latest changes.

You can modify the accept header to specify a version, for example:

curl -L "https://offer.slgnt.eu/api/abc123456/r?widgetid=demo&lang=nl&loc=be"
     -H "accept: application/json;version=1"

Which will respond with the content format of version=1 and with the response format application/json.

The version parameter is optional. By not specifying the version, the latest version will be used.

Engage uses the conventional HTTP response codes to indicate successful or failed API requests.

Codes in the 2xx range indicate success.

Codes in the 4xx range indicate an input related error or validation restrictions.

Codes in the 5xx range indicate an error with Marigold Engage servers.

all API endpoints related to general Smart Content recommendations.

all API endpoints related to lookup user identification data.