Making Segment-based API Calls
This guide outlines the API specifications for the Real-time Customer Segments feature.
Prerequisites
Integration
Make sure you have integrated the Real-time Customer Segment Pixel.
Knowledge
We recommend that you review the following guides before proceeding:
- Relevance by Segment API: Introduces you to the Relevance by Segment API specification. Real-time Customer Segments API calls work on a similar notion.
- Real-time Customer Segment feature page
Real-time Customer Segments API Requests Overview
In the brSM Search/Category API call, add a new parameter segment to specify the dimension and value to use for segmented results.
The syntax of the parameter looks like this:
segment = <dimension>:<value>
http://core.dxpapi.com/api/v1/core/?account_id=6042&q=shoes&segment=customer_geo:NorthAmerica
Sending segmented (and merchandised by segment) API calls
If the browser has a current segment value, it is passed in the header request to the customer’s web server. The customer web server is responsible for correctly passing the segment into the existing Search, Category, and Pathways API calls.

API request and response process
Which APIs support Real-time Customer Segments
The following APIs support Real-time Customer Segments:
- Product Search API
- Category API
- Pathways API
Sample API Requests
GET https://core.dxpapi.com/api/v1/core/?
segment=customer_tier%3amountain_standard #Segment parameter with name “customer tier”
&account_id=<Bloomreach provided account ID>
&domain_key=example_com
&request_id=8438674018837
&url=http://www.example.com/index.html?q=helmets
&request_type=search
&rows=200
&start=0
&fl=pid
&q=helmets
&search_type=keyword
GET https://core.dxpapi.com/api/v1/core/?
segment=customer_tier%3amountain_standard #Segment parameter with name “customer tier”
&account_id=<Bloomreach provided account ID>
&domain_key=example_com
&request_id=8438674018839
&url=http://www.example.com/index.html?q=C0000R84
&request_type=search
&rows=200
&start=0
&fl=pid
&q=C0000R84
&search_type=category
GET https://pathways.dxpapi.com/api/v2/widgets/category/dl4qy396?
account_id=6702
&_br_uid_2=&_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55
&cat_id=pnb160000000000
&domain_key=documentation_site
&url=https%3A%2F%2Fwww.documentation-site.com
&facet=false
&segment=customer_tier%3amountain_standard #Segment parameter with name “customer tier”
GET https://pathways.dxpapi.com/api/v2/widgets/keyword/1jwq4qjz?
account_id=6702
&_br_uid_2=&_br_uid_2=uid%3D7797686432023%3Av%3D11.5%3Ats%3D1428617911187%3Ahc%3D55
&domain_key=documentation_site
&query=helmets
&url=https%3A%2F%2Fwww.documentation-site.com
&facet=false
&segment=customer_tier%3amountain_standard #Segment parameter with name “customer tier”
Caching
Let's consider that, for a given search query, results will be different by segment. It follows that we need to address caching as part of this implementation.
- If a customer is not caching search and category API request/results pages, there is no effect on the caching infrastructure. Requests are passed as normal.
- If a customer is caching results pages, we need to examine how to achieve that the results pages are cached by the cookie value - the results are cached by segment. It is recommended that this cache life should not exceed 24 hours as segmentation pipelines are recalculated daily.
- Other scenarios will be examined on a per-customer basis.
To get more information on caching, check out our guide.
Updated 10 months ago