openapi: 3.0.3 info: title: Recommendations REST API version: 1.0.0 description: > # Recommendations API Reference 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. # How to integrate There are 2 parts linked to the integration of Recommendations: 1. [Interaction tracking](#section/How-to-integrate/Interaction-tracking) 2. [Requesting recommendations](#section/How-to-integrate/Requesting-recommendations) ## Interaction tracking 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. ## Requesting recommendations 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 Selligent contact. # Getting started 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 Selligent 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 ![](assets/img/sequence-site-cortex.svg) ## Request 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 Selligent 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](#operation/get-personalisation-identification) section. ```json POST https://site-see.slgnt.eu/frontend/api/track ``` with the following JSON properties in the request body: ```JSON { "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: ```JSON { "profileId": "123ABCD45678iY2Q0LWJhNGE4NjFkNzFkMDNmI3MjdjNzYtMWQ2ZC00NTZkL", "profileInfo": { }, "doNotTrack": false, "$$profileId": "abc12345-ae74-a40ad", "$$thirdPartyId": "a123456789" } ``` ## Request Smart Content recommendations 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`. ```JSON 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 Selligent 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](#tag/Smart-Content) section. # REST API basics ## Domain 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 ## URI structure 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. ## Request Format 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. ![](assets/img/cortex-catalog-fields.png) 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` . ![](assets/img/cortex-catalog-fields-1.png) ## 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: ```ruby 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. ## Response codes Selligent 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 Selligent servers. | HTTP Status Codes | Description | | -------------------------- | ---------------------------------------------------------------------------------- | | 200 - OK | We found the request resource | | 201 - Created | The resource is successfully created | | 204 - No Content | The requested resources is empty | | 400 - Bad Request | There was an error with the request. The body of the response will have more info. | | 401 - Unauthorized | The access key was incorrect | | 404 - Not found | The resources cannot be found | | 405 - Method Not Allowed | The method is not allowed | | 408 - Request Timeout | The request is taking too long to respond | | 422 - Unprocessable Entity | The resource couldn't be created | | 429 - Too Many Requests | Too many requests hit the API too quickly | | 5xx - Server errors | Something went wrong on our end. Please try again | contact: name: Team Synapse url: https://developers.meetmarigold.com/engage/ email: info@zetaglobal.com license: name: All Rights Reserved url: https://zetaglobal.com/ x-logo: url: ../../assets/logo/zeta_logoLandscape_1Color_WHITE.png backgroundColor: '#1677FF' servers: - url: https://offer.slgnt.eu/api description: Recommendations API server URL for the EU region - url: https://offer.slgnt.us/api description: Recommendations API server URL for the US region paths: /{customerId}/r: parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/widgetId' - $ref: '#/components/parameters/lang' - $ref: '#/components/parameters/loc' get: operationId: get-recommendations-r summary: Get general recommendations description: > Get top-N items recommendations. The most typical use cases are recommendations at overview pages like a homepage or category pages. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/recommendationsResultData' examples: sample-recommendations: $ref: '#/components/examples/sample-recommendations' tags: - Smart Content /{customerId}/r/: parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/widgetId' - $ref: '#/components/parameters/tpid' - $ref: '#/components/parameters/sid' - $ref: '#/components/parameters/lang' - $ref: '#/components/parameters/loc' get: operationId: get-recommendations-r-personalised summary: Get general personalised recommendations description: > Based on user’s past interactions (purchases, view, etc.) with the items, recommends top-N items that are most likely to be of high value for a given user. The most typical use cases are recommendations at overview pages like a homepage or category pages. responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/recommendationsResultData' examples: sample-recommendations: $ref: '#/components/examples/sample-recommendations' tags: - Smart Content /{customerId}/rp/{itemPid}/{item}: parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/itemPid' - $ref: '#/components/parameters/item' - $ref: '#/components/parameters/widgetId' - $ref: '#/components/parameters/lang' - $ref: '#/components/parameters/loc' get: operationId: get-recommendations-rp-item summary: Get recommendations for an item description: > Get recommendations for a specific item. The typical use-case is to offer "related items" or "compatible items" in relation to the specified item. The returned items are sorted by relevance (first item being the most relevant). responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/recommendationsResultData' examples: sample-recommendations: $ref: '#/components/examples/sample-recommendations' tags: - Smart Content /{customerId}/rp/{itemPid}/{item}/: parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/itemPid' - $ref: '#/components/parameters/item' - $ref: '#/components/parameters/widgetId' - $ref: '#/components/parameters/tpid' - $ref: '#/components/parameters/sid' - $ref: '#/components/parameters/lang' - $ref: '#/components/parameters/loc' get: operationId: get-recommendations-rp-item-personalised summary: Get personalised recommendations for an item description: > Get personalised recommendations for a specific item. The typical use-case is to offer "related items" or "compatible items" in relation to the specified item, which includes the past preference of the visitor. The returned items are sorted by relevance (first item being the most relevant). responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/recommendationsResultData' examples: sample-recommendations: $ref: '#/components/examples/sample-recommendations' tags: - Smart Content /{customerId}/r/{item}: parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/item' - $ref: '#/components/parameters/widgetId' - $ref: '#/components/parameters/lang' - $ref: '#/components/parameters/loc' get: operationId: get-recommendations-r-item summary: Get recommendations based on the context description: > Recommends set of items that are related to passed contex. The items returned are selected and sorted based on the relevance for the provided context. The returned items are sorted by relevance (first item being the most relevant). responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/recommendationsResultData' examples: sample-recommendations: $ref: '#/components/examples/sample-recommendations' tags: - Smart Content /{customerId}/r/{item}/: parameters: - $ref: '#/components/parameters/accept' - $ref: '#/components/parameters/customerId' - $ref: '#/components/parameters/item' - $ref: '#/components/parameters/widgetId' - $ref: '#/components/parameters/tpid' - $ref: '#/components/parameters/sid' - $ref: '#/components/parameters/lang' - $ref: '#/components/parameters/loc' get: operationId: get-recommendations-r-item-personalised summary: Get personalised recommendations based on the context description: > Recommends set of items that are related to passed "contex", where the past history of a user is taken into account, allowing personalised recommendations. The items returned are selected and sorted based on the relevance for the provided user and context. The returned items are sorted by relevance (first item being the most relevant). responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/recommendationsResultData' examples: sample-recommendations: $ref: '#/components/examples/sample-recommendations' links: GetProfileByUserId: operationId: get-personalisation-identification parameters: sid: $response.body#/$$profileId tpid: $response.body#/$$thirdPartyId description: > The `id` value returned in the response can be used as the `userId` parameter in `GET /users/{userId}`. tags: - Smart Content /track: servers: - url: https://site-see.slgnt.eu/frontend/api description: SITE API server URL for the EU region - url: https://site-seu.slgnt.us/frontend/api description: SITE API server URL for the US region parameters: - $ref: '#/components/parameters/origin' post: operationId: get-personalisation-identification summary: Get Selligent User identification description: | Get the SITE profile identify based on an internal customer identifier. requestBody: description: '' content: application/json: schema: $ref: '#/components/schemas/siteTrackRequestBody' responses: '200': description: Successful response content: application/json: schema: $ref: '#/components/schemas/siteTrackResultData' examples: sample-track: $ref: '#/components/examples/sample-track' tags: - Site components: parameters: accept: name: accept in: header description: The response format for the data that will be returned. schema: type: string default: application/json;version=1 customerId: name: customerId description: >- ID of the customer. This refers to the uniquer customer property, which is be defined during the customer activation within Recommendations'. in: path required: true schema: type: string format: guid example: '1234567890' item: name: item description: >- The base64 encoded page URL of the item/product. The URL reference of the item for which the recommendations are to be generated. in: path required: true schema: type: string example: >- aHR0cHM6Ly93d3cuc2VsbGlnZW50LmNvbS9wbGF0Zm9ybS9jYXBhYmlsaXRpZXMvYWktbWFjaGluZS1sZWFybmluZw== itemPid: name: itemPid description: >- The item/product ID, like it is referenced by the customer. Typically this is like the item SKU or another unique reference to the item. The ID of the item for which the recommendations are to be generated. in: path required: true schema: type: string example: '1234567890' lang: name: lang in: query required: true description: >- The `lang` parameter is indication to language context. This will influence the translation of the recommended items. schema: type: string example: nl loc: name: loc in: query required: false description: >- The `loc` parameter is indication to location or country context. This will influence the country based offering of the recommended items. schema: type: string example: be origin: name: origin in: header description: >- Domain that is defined in the SITE universe settings (normally domain from the website). schema: type: string example: https://www.example.com sid: name: sid in: query required: false description: The Selligent Site profile ID reference. schema: type: string example: abc12345-ae74-40ad-a9df-9c9107cdf6c8 tpid: name: tpid in: query required: true description: The Selligent system ID of the contact who will see the recommendations. schema: type: integer format: int32 example: 123456789 widgetId: name: widgetid in: query required: true description: >- The widget ID refers to the Smart Content configuration. The configuration decides which algorithm & filter conditions will be used for the recommendations prediction. schema: type: string example: 6f390e664f8c4657b8f88212e98099e1 style: form explode: false schemas: recommendationsResultData: title: Recommendations description: The result of a recommendation. type: array items: $ref: '#/components/schemas/recommendationResultData' recommendationResultData: title: Recommendation description: A recommendation item. type: object properties: item_pid: description: The unique ID for this item within Recommendations. type: string example: SKU-12345 score: description: >- The recommendation score that Recommendations has calculated. The higher the number the better the match. type: integer format: int64 example: 5 tracking_url: description: >- The redirect URL to the item, which is used for reporting views & click. type: string example: >- https://offer.slgnt.eu/api/6f390e664f8c4657b8f88212e98099e1/followedp/5?dId=wjDoTMuEZ-6DXwr4OgJCazlefBpUvoxUHot&lang=fr&loc=be&widgetid=sample item_url: description: The public URL of the item type: string example: https://www.example.com/catalog/jacket-14.html required: - item_pid - score - tracking_url siteTrackRequestBody: description: Site track request type: object properties: universeId: description: Site Universe reference type: string example: 123e4567-e89b-12d3-a456-426614174000 customIdentifier: description: >- A custom identifier by which the user is uniquely defined. Typically, this will be a value by which you will be able to recognize users (for instance login id or guid). type: string example: 1234567abc123 isEvent: description: >- Whether the tracking call represents an event on the website instead of a page visit. type: boolean example: true default: true isIdentificationRequest: description: >- Whether the tracking call is used for identification (which is the main reason of API request). type: boolean example: true default: true isTargeting: description: >- Whether the tracking call is used for targeting (which is not the case for the recommendations API request). type: boolean example: false default: false required: - universeId - customIdentifier - isEvent - isIdentificationRequest - isTargeting siteTrackResultData: description: The Selligent Profile result. type: object properties: profileId: description: The unique ID for this profile within Site. type: string example: >- 123ABCD45678iY2Q0LWJhNGE4NjFkNzFkMDNmI3MjdjNzYtMWQ2ZC00NTZkLThhYzYtYzQ1ZGM2ZTRmYjg4OzczMTY4OTszNjIsz profileInfo: description: The full Site profile, containing offers, tags, ... . type: object $$profileId: description: The Selligent Site identified profile ID reference. type: string example: abc12345-ae74-40ad-a9df-9c9107cdf6c8 $$thirdPartyId: description: >- The Selligent system ID of the user who will see the recommendations. type: string example: '123456789' required: - $$profileId - $$thirdPartyId - profileId examples: sample-recommendations: summary: A sample of recommendation response value: - item_pid: SKU-12 score: 5 tracking_url: >- https://offer.slgnt.eu/api/6f390e664f8c4657b8f88212e98099e1/followedp/12?dId=wjDoTMuEZ-6DXwr4OgJCazlefBpUvoxUHot&lang=fr&loc=be&widgetid=sample item_url: https://www.example.com/catalog/swimsuit-12.html first_category: Women Clothing cat_id: - '250' - item_pid: SKU-15 score: 4 tracking_url: >- https://offer.slgnt.eu/api/6f390e664f8c4657b8f88212e98099e1/followedp/15?dId=wjDoTMuEZ-6DXwr4OgJCazlefBpUvoxUHot&lang=fr&loc=be&widgetid=sample item_url: https://www.example.com/catalog/trousers-12.html first_category: Men Clothing cat_id: - '270' - item_pid: SKU-5 score: 3 tracking_url: >- https://offer.slgnt.eu/api/6f390e664f8c4657b8f88212e98099e1/followedp/5?dId=wjDoTMuEZ-6DXwr4OgJCazlefBpUvoxUHot&lang=fr&loc=be&widgetid=sample item_url: https://www.example.com/catalog/jacket-14.html first_category: Men Clothing cat_id: - '270' sample-track: summary: A sample of Site track response value: profileId: >- 123ABCD45678iY2Q0LWJhNGE4NjFkNzFkMDNmI3MjdjNzYtMWQ2ZC00NTZkLThhYzYtYzQ1ZGM2ZTRmYjg4OzczMTY4OTszNjIsz profileInfo: universeId: 123e4567-e89b-12d3-a456-426614174000 customIdentifier: 1234567abc129 isEvent: true isIdentificationRequest: true isTargeting: false doNotTrack": false $$profileId: abc12345-ae74-40ad-a9df-9c9107cdf6c8 $$thirdPartyId: '123456789' tags: - name: Smart Content x-displayName: Smart Content Recommendations description: all API endpoints related to general Smart Content recommendations. - name: Site x-displayName: Site identification description: all API endpoints related to lookup user identification data. x-tagGroups: - name: Recommendations tags: - Smart Content - name: Site tags: - Site externalDocs: url: https://developers.meetmarigold.com/engage