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:

1. Relevance by Segment API: Introduces you to the Relevance by Segment API specification. Real-time Customer Segments API calls work on a similar notion.
2. 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.

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.

1. 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.
2. 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.
3. Other scenarios will be examined on a per-customer basis.

To get more information on caching, check out our guide.