Calling the Engine API

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 request and include the following:

  • Endpoint
  • Content-type header
  • Body

Endpoint

The endpoint to which Engine API requests are made is as follows:

Engine API Endpoint


The {retailer_shortname} 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 attribute is required within the request body that specifies the account, domain, and instance (for example, "channel": "a-887f2483/p/example.com").

Content-Type Header

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).

Body

The body of an Engine API request consists of JSON that identifies the account and passes page- and user-level data via events.

Events in a Request

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.

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.