Recommend API Guide
The Recommend API endpoint is designed to provide personalized or contextually relevant item recommendations for a pre-configured placement. A placement represents a specific location or scenario within your application (e.g., "homepage_banner", "product_page_alternatives", "checkout_offers") where recommendations are displayed.
Before using this API, ensure the desired placement is configured in the Opti-X platform (or via the Placements API). You'll need the placementKey
generated during this setup.
Endpoint
To fetch recommendations, you'll make a request to:
POST https://api.opti-x.optimove.net/recommend/v1/placements/{placementKey}/recommendations
Replace {placementKey}
with the unique key of your configured placement.
Headers
The following headers are mandatory for all requests:
x-api-key
: Your unique API key provided during integration.x-brand-key
: The unique reference for your brand.content-type
: Must be set toapplication/json
.
Request Body Parameters
The JSON payload of your request provides the context for the recommendation engine. This allows Optimove to tailor the results effectively.
{
"context": {
"product": "Gaming",
"category": "Slots",
"page": {
"url": "casino.graphytecasino.com/en",
"title": "Slots page"
},
"channel": "Mobile"
},
"userId": "123456",
"traits": {
"contextId": "440q6fneh3k-0jot24y2k-76umam8"
},
"type": "recommendation",
"recommendation": {
"target": {
"exclusions": {
"inBetSlip": false,
"additionalItemList": [
832831914
]
}
}
}
}
Here's a breakdown of the request body parameters:
Parameter | Type | Mandatory/Optional | Description | How it Affects Results |
---|---|---|---|---|
userId | String | Mandatory | The unique identifier for the end-user. | Crucial for personalization. If a known user, their past behavior, preferences, and history will heavily influence the recommendations. For anonymous users, a temporary ID can be used for session-based personalization. |
type | String | Mandatory | Defines the type of request. For this endpoint, it should generally be "recommendation" . | Ensures the request is processed by the recommendation engine. Other types might be used for different API functionalities. |
context | Object | Mandatory | An object containing contextual information about where the recommendation is being requested. | Provides the immediate situation/environment, allowing the API to refine recommendations. E.g., showing "slot games" if the user is in the "Slots" category. |
context.product | String | Optional | The product vertical the user is currently interacting with (e.g., "Gaming", "Sports", "Ecommerce"). | Helps filter recommendations to the relevant product line. Different products might have different item types or recommendation strategies. |
context.category | String | Optional | The specific category within the product the user is viewing (e.g., "Slots", "Football", "Dresses"). | Narrows down the recommendations to items within that category. If product is "Gaming", category "Slots" will focus on slot games. |
context.page | Object | Optional | Details about the page where the recommendations will be displayed. | Can be used to understand the specific location within your application, potentially influencing recommendations based on page type or content. |
context.page.url | String | Optional | The URL of the page. | Provides more specific context. |
context.page.title | String | Optional | The title of the page. | Provides more specific context. |
context.channel | String | Optional | The channel through which the user is interacting (e.g., "Mobile", "Desktop", "App"). | May influence the format or type of recommendations if different channels have different display capabilities or user behaviors. |
traits | Object | Optional | An object for additional, often dynamic, contextual attributes. | Allows for sending more granular, real-time context that might not fit standard fields. |
traits.contextId | String | Optional | A specific identifier for the context, which could be a session ID or a page-specific ID. | Can be used for fine-grained contextual filtering or tracking. |
recommendation | Object | Optional | An object to include more specific controls over the recommendations, such as exclusions. Often used in specific scenarios like Sports betting. | Allows direct manipulation of the recommendation output by specifying items to exclude. |
recommendation.target | Object | Optional | Contains targeting rules for the recommendation. | Defines what items should be considered or explicitly excluded. |
recommendation.target.exclusions | Object | Optional | Specifies items or types of items to exclude from the recommendation results. | Ensures that users are not shown irrelevant, already interacted-with, or out-of-context items. |
recommendation.target.exclusions.inBetSlip | Boolean | Optional | Specific to Sports betting. If true , indicates the recommendation is being displayed on the bet slip. | Can trigger rules to avoid recommending markets already in the bet slip or to suggest complementary bets. |
recommendation.target.exclusions.additionalItemList | Array | Optional | Specific to Sports betting. A list of selection/item IDs that are already in the user's basket (e.g., bet slip). | Prevents the API from recommending items (e.g., specific bets) that the user has already added to their current selection/cart. The API will exclude any selections from events that contain an item in this list. |
Note: The availability and behavior of certain optional parameters, especially within the
recommendation.target.exclusions
object, might be highly dependent on thecontext.product
(e.g., "Sports" vs. "Gaming") and your specific Optimove tenant configuration. Always refer to the full Open API Specification in the Developer Tools section of the Opti-X platform for the most precise details.
How Parameters Influence Results - A Summary
userId
is key for personalization: It links the request to a user's profile, history, and preferences.context
object sets the scene: It tells the API where and what the user is currently doing, ensuring relevance.product
andcategory
are strong filters for the type of items to recommend.
recommendation.target.exclusions
provides fine-grained control: It allows you to explicitly remove certain items, which is particularly useful in dynamic contexts like a sports betting slip or a shopping cart.
By providing as much relevant information as possible in these parameters, you enable the Optimove recommendation engine to deliver more accurate, engaging, and effective recommendations.
Example Request: Gaming Context
This is a typical request for recommendations within a gaming product, specifically on a slots page viewed on a mobile device.
{
"context": {
"product": "Gaming",
"category": "Slots",
"page": {
"url": "casino.graphytecasino.com/en",
"title": "Slots page"
},
"channel": "Mobile"
},
"userId": "123456",
"traits": {
"contextId": "440q6fneh3k-0jot24y2k-76umam8"
},
"type": "recommendation"
}
Example Response: Gaming Context
A successful request will return a list of recommended items.
{
"recommendation": {
"result": [
{
"game": {
"game_code": "gameiomslingorainbowriches",
"score": 0.6708955335834027,
"rank": 1
}
}
// ... other recommended items
],
"recId": "1326e3b1-0ecc-4baf-9714-ff2ad4f1ebab",
"recDateTime": "2020-02-26T21:08:57.767Z",
"explanation": {
"reason": "tagged games",
"tag_type": "portlet",
"tag": "MOST POPULAR"
}
}
}
Key Response Fields:
recommendation.result
: An array of recommended items. The structure of each item (e.g.,game
,selection
) will depend on thecontext.product
and placement configuration.score
: The relevance score assigned by the recommendation engine.rank
: The position of the item in the recommended list.
recId
: A unique identifier for this specific recommendation response. Useful for logging or feedback loops.recDateTime
: Timestamp of when the recommendation was generated.explanation
: Provides insight into why these items were recommended (e.g., based on "MOST POPULAR" tag, collaborative filtering, etc.). This can vary based on the recommendation strategy employed by the placement.
Example Request: Sports Context with Exclusions
This example demonstrates a request for a "Sports" product, specifically "Football," and includes exclusions to prevent recommending items already in the user's bet slip.
{
"context": {
"product": "Sports",
"category": "Football",
"page": {
"url": "sport.graphyte.ai",
"title": "Football"
}
},
"recommendation": {
"target": {
"exclusions": {
"inBetSlip": false,
"additionalItemList": [
832831914
]
}
}
},
"userId": "1",
"type": "recommendation"
}
The recommendation.target.exclusions
object here tells the API to:
- Consider that these recommendations are not for display directly on the bet slip (
inBetSlip: false
). - Exclude any recommendations related to item
832831914
(and other selections from the same event) as it's already in the user's bet slip (additionalItemList
).
Example Response: Sports Context
The response will contain sports-related selections, respecting the exclusions.
{
"recommendation": {
"result": [
{
"selection": {
"selectionKey": 1196055705,
"selectionName": "Brighton",
"marketName": "Match Betting",
// ... other selection details
"score": 0.6222013974969091,
"rank": 1
}
}
// ... other recommended selections
],
"recId": "d3df0134-9262-4c8d-9241-ab56043fe7f0",
"recDateTime": "2020-12-16T16:34:00.376Z"
}
}
Example Request: E-commerce Context
The request includes context about the current product being viewed (currentItemId
), the category, and items to exclude (e.g., from the cart).
{
"context": {
"product": "Ecommerce",
"category": "Electronics - Laptops",
"currentItemId": "SKU_LAPTOP123",
"page": {
"url": "https://yourshop.example.com/products/electronics/laptops/sku_laptop123",
"title": "SuperFast Laptop Pro - Product Details"
},
"channel": "Desktop"
},
"userId": "user_ecom_67890",
"traits": {
"customerSegment": "power_user",
"lastPurchaseDaysAgo": 30
},
"type": "recommendation",
"recommendation": {
"target": {
"exclusions": {
"additionalItemList": ["SKU_MOUSE456", "SKU_KEYBOARD789"]
}
}
}
}
Key E-commerce Request Parameters in this example:
context.product
: Set to"Ecommerce"
to indicate the retail vertical.context.category
: Specifies the category of the item currently being viewed (e.g.,"Electronics - Laptops"
). This helps narrow down the type of related items.context.currentItemId
: Crucial for PDP recommendations. This is the unique identifier (e.g., SKU) of the product the user is currently viewing. The recommendation engine uses this to find related or complementary products.recommendation.target.exclusions.additionalItemList
: An array of item IDs (SKUs) that should be excluded from the recommendations. This is commonly used to list items already in the user's shopping cart or recently purchased items.
Example Response: E-commerce Context
The response contains a list of recommended e-commerce items, with details relevant to a shopping experience.
{
"recommendation": {
"result": [
{
"item": {
"item_id": "SKU_SSDEXT1TB",
"name": "UltraSpeed Portable SSD 1TB",
"brand_name": "DataFast",
"category_path": "Computer Accessories - External Storage",
"price": 129.99,
"currency_code": "USD",
"thumbnail_url": "https://yourshop.example.com/images/sku_ssdext1tb_thumb.jpg",
"product_url": "https://yourshop.example.com/products/accessories/storage/sku_ssdext1tb",
"in_stock": true,
"score": 0.92,
"rank": 1
}
},
{
"item": {
"item_id": "SKU_LAPTOPSTAND01",
"name": "Ergonomic Laptop Stand - Silver",
"brand_name": "ComfortView",
"category_path": "Computer Accessories - Stands",
"price": 39.95,
"currency_code": "USD",
"thumbnail_url": "https://yourshop.example.com/images/sku_laptopstand01_thumb.jpg",
"product_url": "https://yourshop.example.com/products/accessories/stands/sku_laptopstand01",
"in_stock": true,
"score": 0.88,
"rank": 2
}
}
// ... other recommended items
],
"recId": "rec-ecom-pdp-9f7ad83b-f938-4a8e-8b2d-1c9e4f6a0b7e",
"recDateTime": "2025-06-04T16:10:00Z",
"explanation": {
"reason": "Cross-sell based on viewed item SKU_LAPTOP123",
"tag_type": "product_detail_page_slot",
"tag": "Frequently Bought Together"
}
}
}
Key E-commerce Response Fields in this example:
item
: Each object in theresult
array represents a recommended product.item_id
: The unique identifier or SKU of the recommended product.name
: The display name of the product.brand_name
: The brand of the product.category_path
: The category breadcrumb or path for the product.price
: The selling price of the item.currency_code
: The currency for the price (e.g.,"USD"
,"EUR"
).thumbnail_url
: URL for a small image of the product.product_url
: Direct URL to the product's detail page.in_stock
:Boolean
indicating stock availability (important for e-commerce).score
&rank
: Standard recommendation metrics.
Note: It is expected that a
200 status code
will be delivered even if there are no suitable recommendations available. In such cases, therecommendation.result
array will typically be empty.
Open API Specification
For the most comprehensive and up-to-date details on all API endpoints, parameters, data types, and mandatory/optional fields, please refer to the full API specification available within the Developer Tools section of the Opti-X platform.
Updated 1 day ago