Monetate Decision API

openapi: 3.2.0
info:
  description: 'The Monetate Engine API allows clients to request decisions (in terms of actions) when an event occurs.

    '
  version: 1.0.0
  title: Monetate Engine Decision API
  termsOfService: http://monetate.com/terms/
  contact:
    name: api@monetate.com
servers:
- url: https://engine.monetate.net/api/engine/v1
tags:
- name: Decision
paths:
  /decide/{retailerShortname}:
    post:
      tags:
      - Decision
      summary: Request Decisions
      description: 'Monetate Decision API

        '
      operationId: decide
      parameters:
      - name: retailerShortname
        in: path
        description: Shortname of the retailer.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: The request was succesful and the payload will include valid actions.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpResponseBody'
        '400':
          description: 'Invalid request.

            The request was either malformated (did not follow this specification), or the data sent was invalid.'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HttpResponseBody'
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/HttpRequestBody'
        description: The request containing the events requiring decisioning.
        required: true
components:
  schemas:
    Action:
      type: object
      required:
      - actionType
      properties:
        actionType:
          type: string
          description: The value that identifies the type of action.
        impressionId:
          type: string
          description: A token to be used for recording managed impressions.
        impressionReporting:
          description: This array identifies the experience and variant associated with the action. It's included for each action if the "includeReporting" option is set to true on the DecisionRequest event.
          type: array
          items:
            $ref: '#/components/schemas/ImpressionReporting'
      discriminator:
        propertyName: actionType
      description: 'Parent class for all actions, which dictates required field.

        '
      example: "{\n    \"actionType\": \"Action\"\n}\n"
    HttpRequestBody:
      type: object
      required:
      - events
      properties:
        deviceId:
          description: A persistent device identifier accepted in place of a monetateId (e.g., iOS identifierForVendor).
          type: string
        customerId:
          description: An identifer specific to a customer, regardless of the device they are on.
          type: string
        events:
          description: An array of events to process.
          type: array
          items:
            $ref: '#/components/schemas/Event'
        monetateId:
          description: A persistent device identifier accepted in place of deviceId. This identifier is generated by Monetate in response to a request containing neither deviceId nor monetateId, or generated and stored in the mt.v cookie on a domain using a Monetate JavaScript integration.
          type: string
        preview:
          description: A token to access actions for a specific variant of an experience, even if the experience is not actively running. The token is generated by clicking the PREVIEW button on the Experience Editor page in Monetate's UI, which will redirect to the client site, appending the token to the URL as ?preview=token, for use in the request.
          type: string
        channel:
          description: A string that identifies the account, domain, and instance associated with the request.
          type: string
        sdkVersion:
          description: A string that identifies the Monetate SDK used to generate the request.
          type: string
      description: 'A JSON request body to process.

        '
      example: "{\n    \"deviceId\": \"device id\",\n    \"monetateId\": \"monetate id\",\n    \"preview\": \"preview token\",\n    \"customerId\": \"customer id\",\n    \"events\": [\n        {\n            \"eventType\": \"Event\"\n        }\n    ]\n}\n"
    Response:
      type: object
      required:
      - requestId
      - actions
      properties:
        requestId:
          type: string
          description: The request identifier tying the response back to an event.
        actions:
          type: array
          description: The array of actions.
          items:
            $ref: '#/components/schemas/Action'
      description: 'A single response, which will include a requestId to link it back to the event,

        and an array of actions.

        '
      example: "{\n    \"requestId\": \"12345\",\n    \"actions\": [\n        {\n            \"actionType\": \"Action\"\n        }\n    ]\n}\n"
    ImpressionReporting:
      type: object
      required:
      - experience_id
      - experience_label
      - experience_name
      - variant_label
      - is_control
      - control_allocation
      - experience_type
      - has_targets
      - tags
      properties:
        experience_id:
          type: integer
          description: The unique identifier for the experience associated with the action.
        experience_label:
          type: string
          description: A static reporting label, set at experience activation, based on experience name.
        experience_name:
          type: string
          description: The title of the experience associated with the action.
        variant_label:
          type: string
          description: The name of the variant associated with the action.
        is_control:
          type: boolean
          description: Whether the user was assigned to a control group for this action.
        control_allocation:
          description: A value from 0.0 to 1.0 representing the percentage of traffic allocated to the control group.
        experience_type:
          type: string
          description: The type of experience (e.g., "100% Experience" or "Majority Fit").
        has_targets:
          type: boolean
          description: Indicates whether there are any WHO targets associated with the experience.
        tags:
          type: array
          items:
            type: string
          description: An array containing the tag names associated to the experience.
      description: 'Identifies the experience and variant associated with the action.

        '
      example: "{\n   \"experience_id\": 1,\n   \"experience_label\": \"Homepage Hero Replacement\"\n   \"variant_label\": \"New Arrivals\",\n   \"is_control\": False,\n   \"control_allocation\": 0.50,\n   \"experience_type\": \"Standard Test\",\n   \"has_targets\": False,\n   \"tags\": [\"Default\"]\n}\n"
    HttpResponseBody:
      type: object
      required:
      - data
      properties:
        data:
          description: The data portion of the response.
          $ref: '#/components/schemas/ResponseData'
        meta:
          description: The metadata portion of the response.
          $ref: '#/components/schemas/Meta'
      description: 'Top-level object definition for the entire HTTP response.

        '
      example: "{\n    \"meta\": {\n        \"code\": 200,\n        \"errors\": [],\n        \"warnings\": [],\n        \"monetateId\": \"monetate id\"\n    },\n    \"data\": {\n        \"responses\": [\n            {\n                \"requestId\": \"12345\",\n                \"actions\": [\n                    {\n                        \"actionType\": \"Action\"\n                    }\n                ]\n            }\n        ]\n    }\n}\n"
    Meta:
      type: object
      properties:
        code:
          type: integer
          description: The HTTP status code associated with the response.
        errors:
          description: An array of objects describing any errors that occurred.
          type: array
          items:
            type: object
        monetateId:
          description: A unique device identifer generated by Monetate when neither deviceId nor monetateId are supplied in request, for persisting to device and sending in future requests. Any events received in request are associated with this monetateId.
          type: string
        warnings:
          type: array
          items:
            type: object
      description: 'Container for all metadata for the responses, inclusive of errors and warnings.

        '
      example: "{\n    \"code\": 200,\n    \"errors\": [],\n    \"warnings\": [],\n    \"monetateId\": \"monetate id\"\n}\n"
    ResponseData:
      type: object
      properties:
        responses:
          description: The array of all responses.
          type: array
          items:
            $ref: '#/components/schemas/Response'
      description: 'Container array for all responses.

        '
      example: "{\n    \"responses\": [\n        {\n            \"requestId\": \"12345\",\n            \"actions\": [\n                {\n                    \"actionType\": \"Action\"\n                }\n            ]\n        }\n    ]\n}\n"
    Event:
      type: object
      required:
      - eventType
      properties:
        eventType:
          type: string
          description: A value that identifies the type of event.
      discriminator:
        propertyName: eventType
      description: 'Parent class for all events, which dictates required fields.

        '
      example: "{\n    \"eventType\": \"Event\"\n}\n"