Skip to main content

Personalize API


  • Returns content for the given user and placement.


Note:  All parameters are case sensitive.

Important: Only call parameters that you need. RichRelevance operates off a set of APIs that support many applications and clients concurrently. RichRelevance may update and enhance these APIs at any time. 

Name Required or Optional Description



A unique key specific to each API implementation. It identifies the specific application or client for reporting, permissions, and merchandising. This is provided by RichRelevance.

Example: apiClientKey=b0126f995ac848159d



A unique key that identifies the site. Each RichRelevance client has a unique API key to separate data and traffic from other clients. This is provided by RichRelevance.

Example: apiKey=4faeaf752ee40a0f

atcid Required on Add to Cart page

Add to Cart ID. This can be a single product ID or a list of product IDs. If more than one product is added to the cart, separate the product IDs by using the pipe "|" character.

Example: atcid=uv2345|xt1234

bi Optional

Block content item(s). This can be a single content ID or a list of content IDs. If more than one content ID is specified, separate the content IDs by using the pipe "|" character.

Example: bi=content__1|content__2



Name of the JavaScript function that JSON data will be passed to. It must be specified for JSONP. The value of this parameter is used as the name of the js function in the response.

Example: callback=products_returned



Omits category data (categoryIds and categories) when set to false. The default is true.

Example: categoryData=false

categoryId Required on category_page

The category ID of the category the merchant wants to investigate. The value must match the external ID provided by the merchant to RichRelevance for the category.

Example: categoryId=902312



Cart value. Used for targeted campaigns involving cart value. It's expressed in cents; for example, $10 is represented as 1000.

Example: cv=9550 (this would equal $95.50)



True/false. If true, it omits the HTML returned in the RichRelevance server response. If false, the response includes the HTML for the placement which is set in the layout of the html field. The default is false. 

Example: excludeHtml=true




The brand featured on the page. Used to set the seed for brand-seeded strategies, such as Brand Top Sellers.

Example: fpb=Microsoft

includeRcs Optional

Includes rcs string when set to true. The default is false. 

Example: includeRcs=true



List of placement identifiers. Each identifier consists of a page type and a placement name. The identifiers are separated by the pipe "|" character.

You'll receive one piece of content per placement. All placements in a call must be for the same page type.

Example: placements=item_page.horizontal|item_page.vertical



Shopper’s referrer prior to viewing the page. Used for reporting and merchandising. This is highly recommended.

Example: pref=


Required on item_page, add_to_cart_page, purchase_complete_page, and cart_page (when not empty)

A single product ID, or a list of product IDs. Part of an order definition on the purchase complete page. Use the pipe "|" character to separate the product IDs.

Example: productId=uv2345|xt1234

rcs Optional First party cookie string. This is a encrypted value of richrelevance cookies. It should be passed as it was received in the earlier api response.



Products the shopper has purchased in the current session. This can be a single product ID or list of product IDs. Products listed here will be considered along with historical data from the RichRelevance system. Use the pipe "|" character to separate the product IDs.

Example: recentlyPurchased=uv2345|xt1234

rid Optional

Region ID. Must be consistent with the ID used in the Engage Content Feed.

Example: rid=Switzerland-France



Identifies a single visit by a shopper.  Sessions are used by behavioral models (to scope user behaviour in a shopping session) and reporting metrics.

Example: sessionId=93484



Supply user segments. Used for segment-targeted campaigns. List each segment using the format segment_number:segment_name, and then use the pipe "|" character to separate segments. You must pass both the segment ID and a segment name for each segment.

Example: sgs=101:NewUser|202:Male

ssl Optional

When set to true, returns http/https depending on how the variable is named in the layout.




Custom keys and values that describe the current shopper. Separate information using a semicolon and the pipe "|" character.

Example: userAttribute=eye_color:blue;green|hair_color:brown



User ID. A unique string to identify each shopper (user). All shopper behavior is stored using this key. It is case-sensitive, and should be the same user ID sent to RichRelevance in other applications.

Example: userId=0982347

If no userID is given, recommendations are based on view and purchase history (via the recentlyViewed and recentlyPurchased parameters or cookies) as well as unpersonalized strategies such as CategoryBestSellers. 

Example Request

Example Response

    request: {
        apiKey: "abcd09875",
        clientKey: "f54ea54cb24",
        placements: [
        sessionId: "null",
        userId: "null"
    rcs: "eF4Ny7ERgDAMA8AmFbuIQ1gO8QbMEZOCgg6YH77_Up7cxaV1DkPPcMhMUGdFrh6xDY8c63S993nM0QJ0mazWZhTxD_ADc7cRDQ",
    placements: [
            creatives: [
                    DESTINATION_URL: "",
                    START_TIME: "00:00",
                    END_TIME: "00:00",
                    MEDIA_URL: "",
                    trackingUrl: "N/A",
                    SIZE: "six-by-one",
                    campaign: "Joululahjaideat 2018 6x1",
                    ALT_TEXT: "Joululahjaideat. Tilaa kätevästi netistä",
                    R_RECOMMEND: "true"
            html: "",
            placement: "home_page.promotion_top_01"
    message: "",
    status: "ok"


Field Description
placements List of placements with promotions based on the request. This is an array of JSON objects, each describing a single placement..

A list of the creatives to be displayed. In most cases, this will only be one.

Destination URL will be converted for clickTracking purposes and will redirect to the original click through URL

html Fully formed HTML for the placement based on the layout and selected campaign. It is included in the response by default. Turn off by using the excludeHtml request parameter.
status A list of the creatives to be displayed. In most cases, this will only be one.
errormessage Either ‘ok’ or ‘error’.
request The parameters from the request that RichRelevance used in processing the request. Typically used for testing purposes.


  • Was this article helpful?