Calling the Personalized Search API

A request is comprised of three parts:

You can include both suggestions and queries in a request.

A Monetate Personalized Search API request is a POST call to the following URL:

Here's the basic Personalized Search API request:

Refer to Auto-Suggestions for the required and optional objects, arrays, and key-value pairs for the suggestions array in the request body. Refer to Personalized Site Search Queries and Personalized Category Page Queries, respectively, the required and optional objects, arrays, and key-value pairs for the recordQueries array in the request body.

The basic response is as follows:

Each Personalized Search API request must include a search token (searchToken). This opaque token contains information about the customer—such as the customer's monetateId and products that the customer previously viewed—as well as information about the experience and its configuration so that the personalization components can be applied to the results contained in the Personalized Search API response.

The first step of obtaining a search token is to create and activate an Omnichannel Personalized Search experience in the Monetate platform. Once you activate that experience, send a request to the Engine API on page load to receive the search token in the response. Include the token in requests that you send to the Personalized Search API endpoint while the customer is on that page. When the customer moves to a different page, request a new search token from the Engine API.

The endpoint for the search token request is as follows:

Replace {retailerShortname} with the parent value of your account. This identifier is provided by your dedicated Services team. You can also find it on the API tab of the Integration page of the Monetate platform settings.

Ensure that you include the Content-type header parameter in the request. Monetate recommends setting its value to text/plain. Furthermore, ensure that the value of channel in the request body correctly specifies the account , instance, and domain. You can find this information in the URL when you are logged into the Monetate platform.

Here's an example of the search token request body:

Here's the response to the example Engine API request: