Request structure and objects

The following table describes the objects and keys that you can include in a request data:




Provides the text or phrase used as search term.

The following key is related to the query object:

  • exact_match - A Boolean flag that allows you to control the search using the exact keyphrase.


Attributes used to further narrow query results.


Selected facets applied to content results.


Tips and guidance for subsequent queries including autocomplete and related searches.


The identifier for the specific location on the page to display search or recommendations. It contains two IDs: rfkid and widget_id but you must specify only rfkid.


The grouping of multiple requests into a single request. It has a list of objects that you can use to override specific request keys or values.


To avoid duplicate responses when you request multiple recommendation widgets on the same page request, you must use a batch object when


The expected information in the search result. The following keys are related to the request for content:

  • sort - order of the items in the response.

  • n_item - total number of items expected per page returned in the response.

  • page_number - page number of the results returned.


Rendering information contained in the HTML, CSS, and JavaScript templates and variables associated with the given widgets.


Indicates that a request is a preview request.


Additional parameters that might affect the search results. The following keys are related to the request for context:

  • user - information about the user such as user ID, gender, and email address.

  • browser - information about the browser including device, user agent, and screen size.

  • geo - a user's geographic information.

  • store - store information that you can use to limit the search to a specific store's inventory.

  • fitment - information that represents the user's fitment choice.

  • page - context of the page such as referrer, page URL, page title, and list of SKUs (for cart page).

  • channel - specific type of channel such as notification bar, chatbot, and web page.

  • campaign - paid campaign information that ties campaigns to rules.


Contains the keys and fields of the specific context applied to the current request.


Specifies the order of the search results.

Mandatory keys

When you construct your JSON request, you must pass these keys irrespective of any other object you add to your request:

  • The page uri to identify the page that the user is on.

  • If applicable to your implementation, locale.locale_country and locale.locale_language. to identify the country and language of the user.

  • Theuser_id or uuid to uniquely identify the user.

  • The widget rfkid to identify the Discover widget that you want to integrate.


    If your Customer Engagement Console (CEC) configuration allows it, you can request all widgets. In this case, you do not need to specify a widget.

Here is a sample request with mandatory keys:

    "context": {
        "page": {
            "uri": "/search",
            "locale_country": "us",
            "locale_language": "en"
        "user": {
            "uuid": "sampleUUID"
    "widget": {
        "rfkid": "rfkid_7"

Do you have some feedback for us?

If you have suggestions for improving this article,