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 Optimove Personalize (formerly 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 to application/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:

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 and category 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 the context.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:

1. Consider that these recommendations are not for display directly on the bet slip (inBetSlip: false).
2. 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 the result 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.

Response Validation and Error Handling

The response from the Recommend API tells you two things: whether the request succeeded, and — on success — what the recommendation engine returned. This section documents every HTTP status code the endpoint returns, the response body for each, and when you'll see them. It also explains a distinction that matters for your integration: an empty result is not an error.

Successful Responses

A successful call returns 200 OK. The response body always contains a recommendation object, and recommendation.result is always a JSON array — a list of recommendation objects, or an empty array ([]) when there are no recommendations to return.

{
  "recommendation": {
    "result": [ ... ],
    "recId": "...",
    "recDateTime": "..."
  }
}

Internal Response Fields

When the x-internal-response header is set on the request, the response includes additional diagnostic fields alongside the standard ones:

HTTP Status Codes

The Recommend API returns the following status codes. Use them to distinguish a successful response (including one with no recommendations) from a client-side request problem and a server-side error.

Success

Client / Validation Errors

These indicate a problem with the request. Fix the request before retrying.

Server Errors

These indicate a problem on the server or a downstream service. The request may succeed on retry.

No Recommendations vs. Errors

A common integration mistake is treating a response with no recommendations as a failure. It isn't.

When the engine has nothing to return for a placement — for example, no eligible items match the context — the API still responds with 200 OK and an empty result array:

{
  "recommendation": {
    "result": [],
    "recId": "...",
    "recDateTime": "..."
  }
}

This is a successful response. Your integration should render its empty or fallback state (for example, hide the placement or show default content), not an error state.

By contrast, a 4xx or 5xx status means the request could not be processed at all — no recommendation decision was made. Treat these as errors.

Handling Errors in Your Integration

Use the status code to decide how to respond:

• 200 with items — Render the recommendations.
• 200 with an empty result — Render your fallback or hide the placement. This is expected behavior, not a failure.
• 400 / 404 — A request problem. Log the response body, fix the request (headers, body, or placementKey), and don't retry the same call unchanged.
• 4xx passed through / 429 — A downstream rejection, often rate limiting. Back off and retry.
• 500 / 502 — A transient server-side error. Retry with exponential backoff; fall back to default content if it persists.

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 Optimove Personalize platform.