This guide contains a detailed explanation of all the Parameters used with the different Recommendations and Pathways APIs.
Common API parameters
These parameters are available for all Recommendations and Pathways APIs regardless of the type of API.
Parameter name | What (What the parameter is) | Why (Why the parameter is needed) | How (How you can obtain its value) |
|---|---|---|---|
| account_id | Your site's numerical Bloomreach account ID. Example: 6702 | This ID is required to uniquely identify your account. | Your Bloomreach representative gives your site's account ID to you before or during your integration kickoff meeting. |
| _br_uid_2 | A first-party cookie created by the Bloomreach tracking pixel library (BrTrk). Example: &_br_uid_2=uid%3D 7797686432023%3Av%3D11.5% 3Ats%3D1428617911187%3Ahc%3D55 | This cookie creates a unique, anonymous identifier for every browser or device. | Mostly the default value provided is used, which is already encoded. |
| domain_key | The site version's domain ID is for the domain where you want to receive your Bloomreach API requests. Example: documentation_site | This parameter identifies the specific site version when one account ID hosts multiple site versions with unique characteristics, such as language versions. | Provided by your Bloomreach representative while scoping and integration. |
| fields | A comma-separated list of fields to be sent in the request. Alternatively, you may configure the fields in the Widget Configurator in the Dashboard instead. This parameter is required if not sent via the Dashboard. Example: &fields=price,color | Only the attributes passed in the fields parameter will be returned in the doc section of the response. | Attributes must be enabled and mapped by Bloomreach. |
| filters | The filter parameter applies a faceted filter to the returned products, searching for products that fit your parameter values. When filtering by an attribute, ensure that the attribute name is enclosed in quotes. Example: &filter="Manufacturer Name":"Pacifichome"Use cases You can also filter results based on numeric ranges. For example, &filter=price:[100 TO *].To provide multiple filters, send multiple filter parameters. For example, &filter=price:[* TO 100]&filter=color_groups:blue.Please note that the below operations are not supported - a negative filter on ranges - SKU-level attribute range filtering is only available for Pathways widgets, not Recommendations widgets. Product-level attribute range filtering is supported for both Pathways and Recommendations widgets. | To narrow down and get more specific results. | Any facet that you want to filter must be in your feed. Attributes must be enabled and mapped by Bloomreach. Let your Bloomreach representative know which attributes in your content feed you want to apply as filters to search results. |
| ref_url | URL or the page from where your visitor came to your site. Example: https://example.com/email-red-dress | Required if you want to use Targeting. Helps to track the journey. | Fetch the URL of the page as you desire. |
| request_id | An ID to track site visitor clicks. Bloomreach doesn't automatically enforce any requirements for this parameter. For example, you can enter "test" as your value for each instance of the request_id parameter without triggering an error message. However, using a unique value allows us to help you if you encounter a problem. Example: 27qeut4b29kqu | It helps track the APIs. | It is recommended that you generate unique, random values of 13 digits to enable click-tracking. |
| rows | The number of matched items to return per results page in the API response. Example: 50 | To allow pagination and manageable results. | Determined by the user as per need. To enhance performance, limit this value to the number of items that you think is reasonable for a single page of search results. |
| url | The absolute URL of the page where the request is initiated. Do not use a relative URL. Example: https://www.documentation-site.com | To identify the origin of the request. | Use the absolute URL of the page. |
| user_id | The universal customer ID of the user (visitor). You only need to pass this field if your particular integration tracks customers this way. Example: kjhh837hsj29h | The parameter captures user IDs from the customer side and reuses the information when powering apps or enhancing cross-device linking. In this way, Bloomreach recognizes users in a way that's aligned with your system. | Decided and shared by you. Use an anonymous string. Don't use email or other personally identifiable information. |
| view_id | A unique identifier for a specific view of your product catalog. Example: homeoasis_ca_en | If you have multiple versions of your site, each with their own product catalog characteristics like product titles and prices, then add view_id to your call. Bloomreach uses your view_id parameter value to display the right product information for your customers based on their individual site views. | view_id for different views are decided by Bloomreach and the customers when scoping during the integration process. |
| widget_id | It’s a unique identifier assigned to widgets when they are created on the Widget Configurator. Example: 1jwp539z | This parameter is used to identify a specific widget while consuming the widget APIs. | The ID of the widget, which can be found in the Widget Configurator in the Dashboard. |
Endpoint-specific Parameters
These parameters are only available for selected Recommendations and Pathways endpoints. The ones which they can be used with is also mentioned in the table.
Parameter name | What (What the parameter is) | Why (Why the parameter is needed) | How (How you can obtain its value) | Available for which endpoint(s) |
|---|---|---|---|---|
| cat_id | Unique ID of the Category present in the feed and pixel. Example: 116715 | For identifying, querying and operating on categories if using a category-based API. | Category ID for each Category is defined in the feed and pixel. |
|
| context_id | contextid takes a single product ID for producing Context-based merchandising results for the widget. Note: In case a context_id is not provided, the system will use Item ID(s) to produce Contextual Merchandising results for the widget. _Example: 4500928You can find more information on the Contextual Merchandising Feature in its guide. | Contextual Merchandising uses Context ID as a primary input for generating the recall set of the widget results. It is highly recommended to pass a context_id whenever a contextual attribute rule is added for a better widget recall set and performance. In the event that not enough results are produced based on context_id, the system depends on Item ID(s) as a fallback to fill the recall set of the widget. | Present in the feed for each item. Choose the ID of the item you want to use for influencing contextual recommendations. |
|
| facet | A boolean for enabling/disabling facets in the response. | Facets are disabled by default. This parameter is used to enable them. | To enable facets, set facet=true. |
|
| filter_facet | It applies a faceted filter to the returned products, searching for products that fit your parameter values. Any facet that you want to filter must be in your feed. For Example, Single filter with multiple values: &filter_facet=color:"red" OR "purple"Multiple filters on different attributes: &filter_facet=color:"red" &filter_facet=brand:"Bloomreach" | With the filter parameter, after a user selects a facet value for filtering, the other facet values in that field are not returned by the API and are no longer visible. The filter_facet parameter allows other facet values to be returned after a facet value has been selected. | Attributes must be enabled and mapped by Bloomreach. You can then apply the facet filter when needed. |
|
| item_ids | Specifies access to a particular set of items. For product catalog, this would be the PID(s). Example: 4427949 | Used to uniquely identify an item for item-based operations. | Present in the feed for each item. |
|
| query | Your site visitor's search query. Search queries are composed of one or more terms. Example: "white sneakers". | To use the query for operations that rely on the user's input. | Query string that is entered by the visitor. |
|
| segment | segment allows you to rank search results based on segment data to serve different experiences to different segments of users.This is used for the Relevance by Segment feature. Example: view_id:abc123 Note: To implement the Real-time customer segments feature, you can refer to its required parameters. | Ranking happens only among items within that segment. More information on the segment parameter can be found here. | The Relevance by Segment feature must be enabled on your account by Bloomreach. If you would like to enable this feature, please consult your Customer Success Manager (CSM) or Business Services Consultant. | Email Recommendation APIs:
|
| sort | Sorts results based on the field value in ascending, descending, or another combination of orders. You can sort any field. Example: sort=sale_price desc sorts in descending order of the sale price. | To get ordered results by default, rather than ordering them on your end in your site's logic. | Value is a field name, followed by asc/desc for ascending/descending order respectively. | Email Recommendation APIs:
|
| start | The number of the first item on a page of results. For example, the first item on the first page is 0, making the start value also 0. The maximum value is 10000. Example: start=3 | Helps with pagination of results. | You can decide the value as per need. | All Email Recs APIs except Item-based |