--- title: Getting Started with the Personalized Search API slug: personalized-search description: Introduction to Monetate's Personalized Search API and its auto-suggestion and full results search types image: https://archbee-image-uploads.s3.amazonaws.com/ceIfEvQHzQk1IVxoRWUh7/K9eTL4jKm7UQINb6zNziJ-20250912-181225.png docTags: createdAt: 2024-07-24T13:10:03.465Z --- A Monetate Personalized Search experience involves the following steps: 1. Create an [Omnichannel experience](https://docs.monetate.com/docs/create-an-omnichannel-experience) configured with an [Omnichannel Personalized Search action](https://docs.monetate.com/docs/configure-omnichannel-personalized-search-action) in the Monetate platform. 2. Return auto-suggestion results as the customer types into the search field. 3. Return complete records as a query when the customer executes a search. :::hint{type="info"} If you've implemented the [Monetate JavaScript API](https://developer.monetate.com/js-api), you can contact your dedicated Customer Success Manager (CSM) to request that custom Personalized Search Results and Personalized Search Suggestions action templates be added to your account so that you can deploy auto-suggestions and site search to your site using a Web experience instead of your own calls to the Personalized Search API. Refer to [Create a Personalized Site Search Experience](https://docs.monetate.com/docs/create-personalized-site-search-experience) for more information. ::: Monetate records all products that a customer views as the result of a search interaction at both the product ID and SKU levels. ## Creating the Search Experience Follow these steps to create the Personalized Search experience: 1. **Obtain the search token.** After you create and activate a Personalized Search experience in the Monetate platform, send a [decision request](docId\:lQST4ABe9zqX_k3ta8Nnh) to the [Engine API](docId\:mChjaGBKMaGu2x17breTP) on page load to [receive a search token](docId\:H-uNB5tzXAAg0GURCZbzB) in the response. This token contains the relevant information for the experience, and it's required for all Personalized Search API calls. Include this token in all Personalized Search API requests made while the customer is on the same page. Request another search token when the customer navigates to another page of your site. 2. **Optionally, configure any redirects.** If the Personalized Search experience has any [URL redirects](https://docs.monetate.com/docs/personalized-search-url-redirects) defined, then you must also make a Personalized Search API call to configure these redirects. URL redirects are predefined search terms that go to a specific page instead of returning a list of search results. Because redirects should not change often, you can cache the configuration and make this call less frequently to improve page load speed. The recommended caching interval is 12 to 24 hours. ::Image[]{src="https://dyzz9obi78pm5.cloudfront.net/app/image/id/668c3998ee361dd810064769/n/search-api-architecture.png" size="90" width="1004" height="883" position="center" alt="Diagram of a Monetate Personalized Search API call. A customer loads a page on a retailer's site, then an Engine API request is made that returns a search token. Optionally, a Search API call for redirect configuration also happens." showCaption="false"} ## Returning Auto-Suggestions Auto-suggestions return live results as the customer types each character in their search term. Results are returned as a response to a Personalized Search API call made after the customer types a new character. This type of request is `"AUTO_SUGGESTIONS"`. ::Image[]{src="https://dyzz9obi78pm5.cloudfront.net/app/image/id/668c39aabf1623de07022617/n/search-api-auto-suggestions.png" size="90" width="1001" height="881" position="center" alt="Diagram of two Monetate Personalized Search API AUTO_SUGGESTIONS calls, one for when a customer types 'a' and another for when the customer types 'b.' The diagram shows how every time the customer types a new letter, a call occurs that returns updated results." showCaption="false"} ## Returning Records for Site Search After the customer executes a search, then the Personalized Search API returns complete product records. An executed search is referred to as a query. The process for a query is as follows: 1. Check for any applicable redirects and handle those as necessary. 2. If no redirects are applicable, use a Personalized Search API call with the search request type `"SEARCH"` to return the records. ::Image[]{src="https://dyzz9obi78pm5.cloudfront.net/app/image/id/668c39ec90f4f16b630f39bd/n/search-api-query.png" size="90" width="1001" height="882" position="center" alt="Diagram of a SEARCH query request. Possible URL redirects are checked first and used if applicable. Otherwise, a Personalized Site Search query request occurs." showCaption="false"} Refer to [Personalized Site Search Queries](docId\:gwGtoOIc_OlMKsSgMarow) for additional information about request requirements. ## Returning Records for Category Pages After a customer arrives on a category page by some means—such as the site's navigation, breadcrumbs, or a site map—then the Personalized Search API can return complete product records in response to a request in which the value of `typeOfRequest` is `CATNAV` and the query is for a specified category path. The value of `categoryPath` is the search criterion the returned products must meet. ::Image[]{src="https://dyzz9obi78pm5.cloudfront.net/app/image/id/67ee939602a47f0af9076002/n/personalized-search-api-category-pages-query-diagram.png" size="90" width="804" height="700" position="center" alt="Diagram of a Personalized Category Pages query request that can occur only after a customer arrives on a product category page. The type of request (typeOfRequest) is "CATNAV" ("typeOfRequest": "CATNAV"). The query object contains the key categoryPath, and its value is the search criterion the returned products must meet." showCaption="false"} See [Personalized Category Page Queries](docId\:iv8baVNFEiaKavV_EzYYT) for additional information about request requirements.