Calling the Engine API
Annotated Example Engine API Request

The following code is an example request to the Monetate Engine API. Each object is described separately afterward.
Example Engine API Request
{
  "deviceId": "IMEI-123456789",
  "monetateId": "2.309132816.1519728587304",
  "preview": "6.3.eJyrVkpMTs4vzSuJz0xRsj...",
  "customerId": "87654321",
  "channel": "a-76ca7dd3/p/example.com",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "12345678",
      "filters": 
      [
        "slot_name"
      ],
      "manageImpressions": false,
      "includeReporting": true
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "79.173.135.170"
    },    
    {
      "eventType": "monetate:context:Coordinates",
      "latitude": "49.566667",
      "longitude": "10.883333"
    },    
    {
      "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:ScreenSize",
      "width": 1024,
      "height": 762
    },    
    {
      "eventType": "monetate:context:Metadata",
      "metadata": 
      {
        "language": "en-GB"
      }
    },    
    {
      "eventType": "monetate:context:CustomVariables",
      "customVariables": 
      [        
        {
          "variable": "VariableName",
          "value": "VariableValue"
        }
      ]
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.com/search",
      "pageType": "search"
    },    
    {
      "eventType": "monetate:context:Referrer",
      "referrer": "http://www.example.com"
    },    
    {
      "eventType": "monetate:record:PageEvents",
      "pageEvents": 
      [
        "myEvent"
      ]
    },    
    {
      "eventType": "monetate:context:ProductThumbnailView",
      "products": 
      [
        "product72",
        "product43",
        "product42"
      ]
    },    
    {
      "eventType": "monetate:context:ProductDetailView",
      "products": 
      [        
        {
          "productId": "product72",
          "sku": "product72-large-green"
        },        
        {
          "productId": "product43",
          "sku": "product43-medium-striped"
        },        
        {
          "productId": "product57"
        }
      ]
    },    
    {
      "eventType": "monetate:context:Cart",
      "cartLines": 
      [        
        {
          "sku": "product72color2",
          "pid": "product72",
          "quantity": 2,
          "currency": "GBP",
          "value": "24.00"
        }
      ]
    },    
    {
      "eventType": "monetate:context:Purchase",
      "purchaseId": "123456789",
      "purchaseLines": 
      [        
        {
          "sku": "product72color2",
          "pid": "product72",
          "quantity": 2,
          "currency": "GBP",
          "value": "24.00"
        }
      ]
    },    
    {
      "eventType": "monetate:record:Impressions",
      "impressionIds": 
      [
        "2.MS4xLjE1MTQ4MDg5MDA"
      ]
    }
  ]
}
{
  "deviceId": "IMEI-123456789",
  "monetateId": "2.309132816.1519728587304",
  "preview": "6.3.eJyrVkpMTs4vzSuJz0xRsj...",
  "customerId": "87654321",
  "channel": "a-76ca7dd3/p/example.com",
  "events": 
  [    
    {
      "eventType": "monetate:decision:DecisionRequest",
      "requestId": "12345678",
      "filters": 
      [
        "slot_name"
      ],
      "manageImpressions": false,
      "includeReporting": true
    },    
    {
      "eventType": "monetate:context:IpAddress",
      "ipAddress": "79.173.135.170"
    },    
    {
      "eventType": "monetate:context:Coordinates",
      "latitude": "49.566667",
      "longitude": "10.883333"
    },    
    {
      "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:ScreenSize",
      "width": 1024,
      "height": 762
    },    
    {
      "eventType": "monetate:context:Metadata",
      "metadata": 
      {
        "language": "en-GB"
      }
    },    
    {
      "eventType": "monetate:context:CustomVariables",
      "customVariables": 
      [        
        {
          "variable": "VariableName",
          "value": "VariableValue"
        }
      ]
    },    
    {
      "eventType": "monetate:context:PageView",
      "url": "https://www.example.com/search",
      "pageType": "search"
    },    
    {
      "eventType": "monetate:context:Referrer",
      "referrer": "http://www.example.com"
    },    
    {
      "eventType": "monetate:record:PageEvents",
      "pageEvents": 
      [
        "myEvent"
      ]
    },    
    {
      "eventType": "monetate:context:ProductThumbnailView",
      "products": 
      [
        "product72",
        "product43",
        "product42"
      ]
    },    
    {
      "eventType": "monetate:context:ProductDetailView",
      "products": 
      [        
        {
          "productId": "product72",
          "sku": "product72-large-green"
        },        
        {
          "productId": "product43",
          "sku": "product43-medium-striped"
        },        
        {
          "productId": "product57"
        }
      ]
    },    
    {
      "eventType": "monetate:context:Cart",
      "cartLines": 
      [        
        {
          "sku": "product72color2",
          "pid": "product72",
          "quantity": 2,
          "currency": "GBP",
          "value": "24.00"
        }
      ]
    },    
    {
      "eventType": "monetate:context:Purchase",
      "purchaseId": "123456789",
      "purchaseLines": 
      [        
        {
          "sku": "product72color2",
          "pid": "product72",
          "quantity": 2,
          "currency": "GBP",
          "value": "24.00"
        }
      ]
    },    
    {
      "eventType": "monetate:record:Impressions",
      "impressionIds": 
      [
        "2.MS4xLjE1MTQ4MDg5MDA"
      ]
    }
  ]
}
﻿
Objects
Device ID
The device ID can be sent with new visitors without mt.v, but it's normally used for apps and similar situations in which cookie IDs are not possible. It's used for targeting and action conditions.
Example deviceID
"deviceId": "IMEI-123456789"
"deviceId": "IMEI-123456789"
﻿
mt.v Value
If no customer identifier is passed in the request, then a monetateID value is returned and the session is considered as a new visitor for targeting and analytics. See User Identity Persistence in Requests﻿ for more information.
Example monetateID
"monetateId": "2.309132816.1519728587304"
"monetateId": "2.309132816.1519728587304"
﻿
Preview Flag
If the session is a preview﻿, then include the token ID for this object for experience and split preview.
Example preview ID
"preview": "6.3.eJyrVkpMTs4vzSuJz0xRsj..."
"preview": "6.3.eJyrVkpMTs4vzSuJz0xRsj..."
﻿
Unique Customer ID
A unique customerID value is used for Customer View and customer datasets﻿.
Example customerID
"customerId": "87654321"
"customerId": "87654321"
﻿
Channel
The channel value is your Monetate account information.
Example channel
"channel": "a-76ca7dd3/p/example.com"
"channel": "a-76ca7dd3/p/example.com"
﻿
Events
The following objects are data passed to Monetate for experiences and analytics.
Action Type Filters, Managed Impressions, and Reporting
The following code example is an Engine API decision request event with filtering for certain action types, managed impressions, and whether to include reporting in the response. The filters parameter can be used to filter certain action types.
Example Request Event for Filtering, Managed Impressions, & Reporting
{
  "eventType": "monetate:decision:DecisionRequest",
  "requestId": "12345678",
  "filters": 
  [
    "slot_name"
  ],
  "manageImpressions": false,
  "includeReporting": true
}
{
  "eventType": "monetate:decision:DecisionRequest",
  "requestId": "12345678",
  "filters": 
  [
    "slot_name"
  ],
  "manageImpressions": false,
  "includeReporting": true
}
﻿
IP Address
The following code example is an Engine API decision request event for the IP address. This information is used for targeting and analytics.
Example Request Event for IP Address
{
  "eventType": "monetate:context:IpAddress",
  "ipAddress": "79.173.135.170"
}
{
  "eventType": "monetate:context:IpAddress",
  "ipAddress": "79.173.135.170"
}
﻿
Coordinates
The following code example is an Engine API decision request event for a customer device's physical coordinates expressed in longitude and latitude. This information is used for targeting and analytics.
Example Request Event for Coordinates
{
  "eventType": "monetate:context:Coordinates",
  "latitude": "49.566667",
  "longitude": "10.883333"
}
{
  "eventType": "monetate:context:Coordinates",
  "latitude": "49.566667",
  "longitude": "10.883333"
}
﻿
User Agent
The following code example is an Engine API decision request event for the User-Agent header. This information is used for targeting and analytics.
Example Request Event for User-Agent Header
{
  "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:UserAgent",
  "userAgent": "Mozilla/5.0 (Macintosh; U; Intel Mac OS X; en) AppleWebKit/522.11 (KHTML, like Gecko) Safari/3.0.2"
}
﻿
Screen Size
The following code example is an Engine API decision request event for the screen size of the customer's device. This information is used for targeting.
Example Request Event for Device Screen Size
{
  "eventType": "monetate:context:ScreenSize",
  "width": 1024,
  "height": 762
}
{
  "eventType": "monetate:context:ScreenSize",
  "width": 1024,
  "height": 762
}
﻿
Metadata
The following code example is an Engine API decision request event for customer-specific metadata. This information is used for targeting and action conditions.
Example Request Event for Metadata
{
  "eventType": "monetate:context:Metadata",
  "metadata": 
  {
    "language": "en-GB"
  }
}
{
  "eventType": "monetate:context:Metadata",
  "metadata": 
  {
    "language": "en-GB"
  }
}
﻿
Custom Variables
The following code example is an Engine API decision request event for a custom variable and its value. This information is used for targeting.
Example Request Event for Custom Variable
{
  "eventType": "monetate:context:CustomVariables",
  "customVariables": 
  [    
    {
      "variable": "VariableName",
      "value": "VariableValue"
    }
  ]
}
{
  "eventType": "monetate:context:CustomVariables",
  "customVariables": 
  [    
    {
      "variable": "VariableName",
      "value": "VariableValue"
    }
  ]
}
﻿
Page View and Type
The following code example is an Engine API decision request event for a page view and its page type. This information is used for action conditions. See Action Condition Mapping﻿ for more details.
Example Request Event for Page View and Page Type
{
  "eventType": "monetate:context:PageView",
  "url": "https://www.example.com/search",
  "pageType": "search"
}
{
  "eventType": "monetate:context:PageView",
  "url": "https://www.example.com/search",
  "pageType": "search"
}
﻿
Referrer
The following code example is an Engine API decision request event for a referring URL. This information is used for targeting and action conditions.
Example Request for Referrer
{
  "eventType": "monetate:context:Referrer",
  "referrer": "http://www.example.com"
}
{
  "eventType": "monetate:context:Referrer",
  "referrer": "http://www.example.com"
}
﻿
Custom Page Events
The following code example is an Engine API decision request event for custom page events. This information is used for analytics.
Example Request for Custom Page Events
{
  "eventType": "monetate:record:PageEvents",
  "pageEvents": 
  [
    "myEvent"
  ]
}
{
  "eventType": "monetate:record:PageEvents",
  "pageEvents": 
  [
    "myEvent"
  ]
}
﻿
Search Results or Product List Pages
The following code example is an Engine API decision request event captures product thumbnail views on search results pages, product list pages. This information is used for targeting and action conditions.
Example Request for Product Thumbnail Views
{
  "eventType": "monetate:context:ProductThumbnailView",
  "products": 
  [
    "product72",
    "product43",
    "product42"
  ]
}
{
  "eventType": "monetate:context:ProductThumbnailView",
  "products": 
  [
    "product72",
    "product43",
    "product42"
  ]
}
﻿
Product Detail Pages
The following code example is an Engine API decision request event captures product detail page views. This information is used for targeting and action conditions.
Example Request for Product Detail Page Views
{
  "eventType": "monetate:context:ProductDetailView",
  "products": 
  [    
    {
      "productId": "product72",
      "sku": "product72-large-green"
    },    
    {
      "productId": "product43",
      "sku": "product43-medium-striped"
    },    
    {
      "productId": "product57"
    }
  ]
}
{
  "eventType": "monetate:context:ProductDetailView",
  "products": 
  [    
    {
      "productId": "product72",
      "sku": "product72-large-green"
    },    
    {
      "productId": "product43",
      "sku": "product43-medium-striped"
    },    
    {
      "productId": "product57"
    }
  ]
}
﻿
Cart Pages
The following code example is an Engine API decision request event captures information about products in a customer's cart. This information is used for targeting, action conditions, and analytics.
Example Request for Carted Products
{
  "eventType": "monetate:context:Cart",
  "cartLines": 
  [    
    {
      "sku": "product72colour2",
      "pid": "product72",
      "quantity": 2,
      "currency": "GBP",
      "value": "24.00"
    }
  ]
}
{
  "eventType": "monetate:context:Cart",
  "cartLines": 
  [    
    {
      "sku": "product72colour2",
      "pid": "product72",
      "quantity": 2,
      "currency": "GBP",
      "value": "24.00"
    }
  ]
}
﻿
Purchases Pages
The following code example is an Engine API decision request event that captures information about products that a customer has finished buying that appear on a "Purchase Complete" or similar page. This information is used for targeting and analytics.
Example Request for Purchased Products
{
  "eventType": "monetate:context:Purchase",
  "purchaseId": "123456789",
  "purchaseLines": 
  [    
    {
      "sku": "product72colour2",
      "pid": "product72",
      "quantity": 2,
      "currency": "GBP",
      "value": "24.00"
    }
  ]
}
{
  "eventType": "monetate:context:Purchase",
  "purchaseId": "123456789",
  "purchaseLines": 
  [    
    {
      "sku": "product72colour2",
      "pid": "product72",
      "quantity": 2,
      "currency": "GBP",
      "value": "24.00"
    }
  ]
}
﻿
Impressions
The following code example is an Engine API decision request event that captures impressions. When manageImpressions is set to true, this event tells Monetate that the impression happened.
Example Request for Impressions
{
  "eventType": "monetate:record:Impressions",
  "impressionIds": 
  [
    "2.MS4xLjE1MTQ4MDg5MDA"
  ]
}
{
  "eventType": "monetate:record:Impressions",
  "impressionIds": 
  [
    "2.MS4xLjE1MTQ4MDg5MDA"
  ]
}
﻿
﻿
Updated 25 Sep 2024
Request Filtering
Engine API and Caching Rules