Offsite & Email Recommendation
Particular Audience’s Offsite & Email Recommendation API is a flexible and robust interface that supports any eCommerce platform or application. The Offsite & Email Recommendation API supports all required requests to run real-time personalization of product slots on any website.
API Base URL
Method: GET
Endpoint: /1.0/ClientRecom
API Response
Each recommendation API has the same response pattern, and this section describes the response object.
Sample Response
| Name | Type | Description |
|---|---|---|
| type | int | Response type. Any value with negative number means error. Ex.: 1 |
| code | int | Response code. Ex.: 0 |
| payload | array of string | Return list of product RefId matched in the recommendation method. Ex.: ["76277"] |
| message | String | Error message in case response type is not successfull. |
Personalized Recommendations
Recommended For You Hybrid Recommender
This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.
Tactic Cascade: ‘Viewed With Recently Viewed’ >> ‘Bought With Recently Viewed’ >> ‘Recently Viewed’ >> ‘Popular Items’
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/Personalized?customerId=CUSTOMER_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| CUSTOMER_ID | string | Query | Customer Id. It will be available after the Config API call. You need to store it for subsequent calls. |
Response
Response is described here
Personalized PDP
Personalized PDP Recommendations
This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.
Tactic Cascade: Viewed With > Bought With > Visually Similar > Viewed With Recently Viewed > Bought With Cart Contents > Recently Viewed > Popular Items (over 7 days)
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ProductDetail?customerId=CUSTOMER_ID&productRef=PRODUCT_REF&items[0]=PRODUCT_REF&items[1]=PRODUCT_REF&filterOutOfStock=false'
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/Cart?customerId=CUSTOMER_ID&items[0]=PRODUCT_REF&items[1]=PRODUCT_REF&filterOutOfStock=false'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| CUSTOMER_ID | string | Query | Customer Id. It will be available after the Config API call. You need to store it for subsequent calls. |
| PRODUCT_REF | string | Query | Product Ref Id. |
| items | array | Query | This takes in an array of Ref IDs in the customer cart (used for Bought with Cart Contents) |
| filterOutOfStock | boolean | Query | Whether to filter out of stock items. |
Response
Response is described here
Similar Items-Based Hybrids
These are Similar Item-based endpoints that have been configured with fall-throughs in case one tactic does not have a result. The fall-through behavior can be seen in the Tactic Cascade description.
Viewed Together + Similar Attributes Hybrid Recommender
This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.
Tactic Cascade: ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Similar Attributes’ >> ‘Popular Items’
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogetherAttributes?productRef=PRODUCT_REF'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
Response
Response is described here
Viewed Together + Visually Similar Hybrid Recommender
This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.
Tactic Cascade: ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Visually Similar’ >> ‘Popular Items’
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogetherVisuallySimilar?productRef=PRODUCT_REF&productStyleId=STYLE_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
| STYLE_ID | string | Query | ProductStyleId being viewed. Required if the website is configured to use StyleId for VSR |
Response
Response is described here
Similar Attributes + Viewed Together Hybrid Recommender
This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.
Tactic Cascade: ‘Similar Attributes’ >> ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Popular Items’
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/SimilarAttributesViewedTogether?productRef=PRODUCT_REF'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
Response
Response is described here
Visually Similar + Viewed Together Hybrid Recommender
This is a hybrid tactic meaning if there are no results for the first tactic, the recommender will try the next one. This fall-through will continue through all the tactics until a result is found.
Tactic Cascade: ‘Visually Similar’ >> ‘Collaborative Filtering Jaccard Items Viewed Together’ >> ‘Popular Items’
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/VisuallySimilarViewedTogether?productRef=PRODUCT_REF&productStyleId=STYLE_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
| STYLE_ID | string | Query | ProductStyleId being viewed. Required if the website is configured to use StyleId for VSR |
Response
Response is described here
Popular Items
Used to return trending products (by purchases) across the website. This tactic is based on all customers’ purchase behavior.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/PopularItems'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
Response
Response is described here
Collaborative Filtering
Collaborative Filtering Jaccard Items Viewed Together
Used to return the list of items that are often viewed with a product. This tactic is based on all customers’ viewing behavior.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogether?productRef=PRODUCT_REF'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
Response
Response is described here
Collaborative Filtering Jaccard Items Bought Together
Used to return the list of items that are often bought with a product. This tactic is based on all customers’ purchase behavior.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/BoughtTogether?productRef=PRODUCT_REF'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
Response
Response is described here
Visually Similar
Used to return the list of items that have similar images to a product. This tactic is based on the image compare program.
Visually Similar Request (by product identifier)
This endpoint will return a list of similar-looking products when given a product identifier.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/OnlyVisuallySimilar?productRef=PRODUCT_REF'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
Response
Response is described here
Visually Similar Request (by style identifier)
This endpoint will return a list of similar-looking products when given a style identifier.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/OnlyVisuallySimilar?productStyleId=STYLE_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| STYLE_ID | string | Query | This is the style identifier. The style identifier is an ID that sits below the product ID but is not as granular as a variant level identifier/SKU. |
Response
Response is described here
Similar Attributes
Used to return the list of items that have similar attributes to a product. This tactic is based on the attributes compare program.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/OnlySimilarAttributes?productRef=PRODUCT_REF'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| PRODUCT_REF | string | Query | Product Ref Id. |
Response
Response is described here
Items Often Bought Together
Items Often Bought Together - Cart Page
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/BoughtTogetherCartContent?items[0]=PRODUCT_REF&items[1]=PRODUCT_REF'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| items | array | Query | This takes in an array of Ref IDs that you want to query for |
Response
Response is described here
Items Often Bought Together - Recently Viewed Items
Used to return the list of items that are bought together with the recently viewed items of the current customer. This tactic is based on all customers’ purchase behavior.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/BoughtTogetherRecentlyViewed?customerId=CUSTOMER_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| CUSTOMER_ID | string | Query | This the customer ID you want to query for. |
Response
Response is described here
Items Often Viewed Together - Recently Viewed Items
Used to return the list of items that are viewed together with the recently viewed items of the current customer. This tactic is based on all customers’ view behavior.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/ViewedTogetherRecentlyViewed?customerId=CUSTOMER_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| CUSTOMER_ID | string | Query | This the customer ID you want to query for. |
Response
Response is described here
Recently Viewed
Used to return the list of items that are viewed in the most recent session. This tactic is based on the current customer’s tracked data.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/RecentlyViewed?customerId=CUSTOMER_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| CUSTOMER_ID | string | Query | This the customer ID you want to query for. |
Response
Response is described here
Historic Viewed Items
Used to return the list of items (maximum 20 items) that are viewed in the previous sessions of the current customer. This tactic is based on that customer’s tracked data.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/HistoricViewed?customerId=WEBSITE_ID'
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
| CUSTOMER_ID | string | Query | This the customer ID you want to query for. |
Response
Response is described here
Bundles: Items Often Bought Together
Used to return sets or a list of items that are bought together with the provided list of item(s) on either a product page or cart page.
Request CURL & Params
curl --location 'https://API_BASE_URL/1.0/ClientRecom/WEBSITE_ID/bundle'
Header Params
| Name | Type | Param Type | Description |
|---|---|---|---|
| WEBSITE_ID | string | Header | Website ID. Available in web app or PA will provide. |
Body Params
| Name | Type | Param Type | Description |
|---|---|---|---|
| product_ref_ids | array | Body | Product Ref Id. |
| setCount | int | Body | Number of bundles/sets to be returned (Default is 1). |
| count | int | Body | Number of items in each bundle/set (Default is 1 + # of product_ref_ids). |
| filter_out_of_stock | boolean | Body | Filter out of stock items. |
Response
| Name | Type | Description |
|---|---|---|
| type | int | Response type. Any value with negative number means error. Ex.: 1 |
| code | int | Response code. Ex.: 0 |
| payload | 2D array of string | Return list of product RefId matched in the recommendation method. Ex.: [["1234", "5678"], ["1234", "8972"]] |