Request Requirements
When an Engine API request is made, Monetate's decision engine evaluates all active Omnichannel experiences in the account and uses the provided context to make decisions about which experiences and actions for which the customer has qualified.
All Engine API requests must be made via a POST to the decision endpoint and include the following:
- Content-type header
- Body
The endpoint for Engine API requests is as follows:
The {retailerShortname} placeholder is a unique identifier that specifies the parent value of the 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.
A subsequent channel key-value pair is required in the request body that specifies the account, domain, and instance (for example, "channel": "a-887f2483/p/example.com").
The content-type header is required and may be set to either application/JSON or text/plain.
Monetate recommends text/plain to avoid an extra round trip (the CORS preflight OPTIONS request associated with application/JSON).
The body of an Engine API request consists of JSON that identifies the account and passes page- and user-level data via events.
Each of the three event types instructs the Engine API to do different things with the associated information:
- Event types that begin with monetate:decision request that the Engine API evaluate active experiences and return actions
- Event types that begin with monetate:context provide information about the visitor or page that Monetate uses for targeting and decision-making purposes
- Event types that begin with monetate:record provide information that Monetate should record but that isn't used for targeting or decision-making purposes
All Engine API requests should follow the same structure as noted in the API reference. However, including various API models depends on individual integrations and use cases.
- Include the pageType parameter within the monetate:context:PageView event to use corresponding action conditions
- Include the monetate:context:UserAgent event and the end user's userAgent value as context for analytics so that stealth sessions are registered properly
- Include the monetate:context:ProductThumbnailView event to communicate all items present on a listing page or search results page, which can then be used for action conditions or advanced Product Recommendations use cases
- Include the monetate:context:ProductDetailView event to communicate a product view has occurred and subsequently target/condition based on a specific product, brand, product type/category, or advanced Product Recommendations use cases
- Include the monetate:context:Cart event to communicate cart contents which are used for behavioral analytics and cart-content targets or action conditions
- Include the monetate:context:Purchase event to communicate a purchase has occurred for behavioral analytics and purchase
See Target, Event, & Condition Mapping for more extensive mapping of Engine API models and how you can use them for targeting and action conditions in experiences and actions.