Calling the Personalized Search API

Monetate's Personalized Search API is the search integration for your applications to implement Personalized Site Search and Personalized Category Pages on your site(s).
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.
Queries: Products that meet the customer's completed 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.
Endpoint
A Monetate Personalized Search API request is a POST call to the following URL:
Personalized Search API Endpoint
https://engine.monetate.net/api/search/v1/site-search/{name}/{instance}/{domain}/search
https://engine.monetate.net/api/search/v1/site-search/{name}/{instance}/{domain}/search
﻿
Basic Request Code
Here's the basic Personalized Search API request:
Basic Personalized Search API Request
{
  "request": {
    "searchToken": "monetate-12345678987654321",
    "suggestions": [
      {
        ... Suggestions query 1 ...
      },
      {
        ... Suggestions query 2 ...
      }
    ],
    "recordQueries": [
      {
        ... Record query 1 ...
      },
      {
        ... Record query 2 ...
      }
    ]
  }
}
{
  "request": {
    "searchToken": "monetate-12345678987654321",
    "suggestions": [
      {
        ... Suggestions query 1 ...
      },
      {
        ... Suggestions query 2 ...
      }
    ],
    "recordQueries": [
      {
        ... Record query 1 ...
      },
      {
        ... Record query 2 ...
      }
    ]
  }
}
﻿
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.
Basic Response Code
The basic response is as follows:
Basic Personalized Search API Response
{
  "meta": {
    ...
  },
  "suggestionResults": [
    {
      ... Results of suggestions query 1 ...
    },
    {
      ... Results of suggestions query 2 ...
    }
  ],
  "queryResults": [
    {
      ... Results of record query 1 ...
    },
    {
      ... Results of record query 2 ...
    }
  ]
}
{
  "meta": {
    ...
  },
  "suggestionResults": [
    {
      ... Results of suggestions query 1 ...
    },
    {
      ... Results of suggestions query 2 ...
    }
  ],
  "queryResults": [
    {
      ... Results of record query 1 ...
    },
    {
      ... Results of record query 2 ...
    }
  ]
}
﻿
Obtaining a Search Token
Before you can make a Personalized Search API request, you must first create and activate  an Omnichannel Personalized Search experience in the Monetate platform, and then send a request to the Engine API﻿. The response contains a search token (searchToken) that you then include in requests that you send to the Personalized Search API endpoint﻿ each time the customer conducts any type of search activity on the same page. Each time the customer navigates to a different page of your site, you must request a new search token from the Engine API to use in Personalized Search API requests for search activity that occurs on that page.
The endpoint for the search token request is as follows:
Engine API Endpoint
https://engine.monetate.net/api/engine/v1/decide/{retailerShortname}
https://engine.monetate.net/api/engine/v1/decide/{retailerShortname}
﻿
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:
Example Engine API Request for Personalized Search Experience
{
  "channel": "a-76ca7dd3/p/example.com",
  "events": [
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "79.173.135.170"
    },
    {
      "eventType": "monetate:context:UserAgent",
      "userAgent": "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en) AppleWebKit/522.11 (KHTML, like Gecko) Safari/3.0.2"
    },
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.com/"
    }
  ]
}
{
  "channel": "a-76ca7dd3/p/example.com",
  "events": [
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "11111"
    },
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "79.173.135.170"
    },
    {
      "eventType": "monetate:context:UserAgent",
      "userAgent": "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en) AppleWebKit/522.11 (KHTML, like Gecko) Safari/3.0.2"
    },
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.com/"
    }
  ]
}
﻿
Here's the response to the example Engine API request:
Example Engine API Response for Personalized Search Experience
{
  "meta": {
    "code": 200,
    "monetateId": "5.1580506437.1738689374564"
  },
  "data": {
    "responses": [
      {
        "requestId": "2e7c7073-42c6-4523-a1f4-512bf4d7b6c4",
        "actions": [
          {
            "actionEvents": [
              "op_click",
              "op_impression"
            ],
            "actionId": 5285641,
            "searchToken": "6.18.eJxdkMtugzAQRf9l1lYEBYPDtu2qkYiippuqQsZMAgkYYpsEHPnfC7RSqu5G58zjau7AhalamVUFJPSJ0Sj0CeDQQeLHAVuHjMaUQDNroCufMo96URjEq1lHbB3E4TQDBDRyJcrspFsJyR1EKw0OZi4VCpQmzU8ojIbkcyGtKn7qZbNtbtajB6PP4Mgv48exR5uHI3-wwqqLxwfe_GG2zntzO_qX7sFKWdZ6tOZ6BfdFwIwdpofdcnWyb5vXj3223aUv--f3qcER6FBNwXldaT6_Y46Nkuc1bv8Lo3p0zn0DBjRm4w.vokF2fCXdo41iZAz93tqd4hij1_YxEqvYzgnBgpwrMg",
            "actionType": "monetate:action:SiteSearchApiAction"
          }
        ]
      }
    ]
  }
}
{
  "meta": {
    "code": 200,
    "monetateId": "5.1580506437.1738689374564"
  },
  "data": {
    "responses": [
      {
        "requestId": "2e7c7073-42c6-4523-a1f4-512bf4d7b6c4",
        "actions": [
          {
            "actionEvents": [
              "op_click",
              "op_impression"
            ],
            "actionId": 5285641,
            "searchToken": "6.18.eJxdkMtugzAQRf9l1lYEBYPDtu2qkYiippuqQsZMAgkYYpsEHPnfC7RSqu5G58zjau7AhalamVUFJPSJ0Sj0CeDQQeLHAVuHjMaUQDNroCufMo96URjEq1lHbB3E4TQDBDRyJcrspFsJyR1EKw0OZi4VCpQmzU8ojIbkcyGtKn7qZbNtbtajB6PP4Mgv48exR5uHI3-wwqqLxwfe_GG2zntzO_qX7sFKWdZ6tOZ6BfdFwIwdpofdcnWyb5vXj3223aUv--f3qcER6FBNwXldaT6_Y46Nkuc1bv8Lo3p0zn0DBjRm4w.vokF2fCXdo41iZAz93tqd4hij1_YxEqvYzgnBgpwrMg",
            "actionType": "monetate:action:SiteSearchApiAction"
          }
        ]
      }
    ]
  }
}
﻿
﻿
Updated 21 Feb 2025
Getting Started with the Personalized Search API
Auto-Suggestions