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. Omnichannel Personalization operates off a set of APIs that support many applications and clients concurrently. Omnichannel Personalization 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

content_ids Optional

List of content IDs. The content returned is the intersection between the list of content ids passed in the API call and the content from the selected Campaign. Mulptiple content IDs are separated by the pipe "|" character.

Example: content_ids=content__13055|13056

Note: The provided contentId's should be external Ids.



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

ipor Optional

Shopper IP address. Only use if the API request is not coming from the shopper’s device (for example, server-side integration).

Example: ipor=

includeRcs Optional

True/false. The default is false. If true, it includes rcs string. 

Example: includeRcs=true

includeScore Optional

True/false. The default is false. If true, the response will include the score of the selected content for each placement. 

Example: includeScore=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, 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

Algonomy Cookie String. This is the encrypted Algonomy cookie for the user associated with the API request. It should be passed exactly as it was received in a prior API response.

Clients should ensure to preserve the 'rcs' value just as it was served. The 'rcs' parameter is always alphanumeric and case-sensitive, with the token value including a mix of uppercase letters, lowercase letters, and numbers.

Note: The 'rcs' parameter allows merchants to effectively provide the Algonomy platform access to a user's Algonomy browser cookie by acting as a cookie proxy (or cookie pass-through). This process involves the merchant reading and writing a user's Algonomy browser cookie and passing it to and from Algonomy via the server-side API.



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.


tagFilter Optional 

Filter contents that match a list of tags using advanced logic such as AND (&&), OR (||), and NOT (!) operators.

Note: You need to URL encode the '&&' operator. To encode a URL with the ampersand character, use %26.

Multiple tags can be passed using the pipe "|" as a separator. When multiple tags are passed, the returned content should have all tags. 

Example: tagFilter=(shoes||women)&&Nike 

Filter of (shoesORwomen) AND Nike

Note: You can also group together the logical expressions to combine multiple expressions.

tagRefinement Optional

Refine contents based on a list of tags. The tags in this list will be applied as a filter if there are matching contents available. But if there are no matching contents, then these tags will not be applied as filters. Multiple tags can be passed using the pipe "|" as a separator.

Example: tagFilter=shoes||women&tagRefinement=Nike

This would attempt to return contents with either 'shoes' AND 'Nike' OR 'women' AND 'Nike'. If no contents have the Nike tag, then it will still return contents with either 'shoes' OR 'women'.

Note: tagRefinement will only be applied if tagFilter is being used. 



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

userAttributeReplace Optional

Usage is same as userAttribute, except that the attributes sent along with userAttributeReplace will replace all previously sent values for that attribute.
Example: userAttributeReplace=eye_color:black
In the above example all previous values of eye_color will be removed and replaced with black.
If the same attribute is sent along in a single request in userAttribute as well as userAttributeReplace, then the value sent in userAttributeReplace will take precedence.
This attribute also supports Delete update against attribute values.

Example: userAttribute=eye_color:|hair_color:



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 Personalization Cloud used in processing the request. Typically used for testing purposes.


  • Was this article helpful?