Calling the Personalized Search API
A request is comprised of three parts:
- Search token: A token used to authenticate the search request that you must obtain by sending a POST request to the Engine API before making the Personalized Search API request.
- Suggestions: Automatic suggestions based on the text currently typed into the search field. Suggestions are updated live as the customer continues to type.
- Record Queries: A search of the mapped product catalog for products that meet the search criteria. An individual result is called a record. Queries occur when the customer formally sends their search request by pressing Enter or clicking a button that triggers the full search.
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.
Ensure that you send a decision request to the Engine API on every page load so that the returned seach token includes the latest information about what products the customer has viewed and other relevant context necessary for the personalization aspect of the Personalized Search API response.
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.

Refer to the Engine API reference as well as Request Requirements and Annotated Example Engine API Request for more information about the Engine API models included in the request body.
Here's an example of the search token request body:
Here's the response to the example Engine API request: