MoEngage Business Events API

openapi: 3.2.0
info:
  title: MoEngage Business Events API
  description: 'API for creating, triggering, and searching business events in MoEngage.


    You can use these events to trigger campaigns whenever they occur. For example, you can create business events for various situations, such as when new episodes of an OTT series become available, when there is a flight delay, or when there is a price drop on an item in a cart.


    **Postman Collections**

    We have made it easy for you to test the APIs. [View in Postman](https://www.postman.com/moengage-dev/workspace/api-docs/collection/3182294-38587f83-f039-46f3-b86e-10af2c918053).

    '
  version: '1.0'
servers:
- url: https://api-{dc}.moengage.com/v1.0
  description: MoEngage API Server
  variables:
    dc:
      default: '01'
      description: The ‘dc’ in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101.
security:
- basicAuth: []
tags:
- name: Business Events
  description: Manage and trigger business events.
paths:
  /business_event:
    post:
      tags:
      - Business Events
      summary: Create Business Event
      description: 'This API creates business events in MoEngage. You can use these events to trigger campaigns whenever they occur. In MoEngage, you can set up event-triggered campaigns to notify users about new episodes, flight delays, or price reductions on items they have viewed, wished for, or added to their carts.

        '
      x-mint:
        content: '#### Rate Limit

          The rate limits are at the workspace level. You can create a maximum of 50 business events for each workspace.

          '
      operationId: createBusinessEvent
      requestBody:
        description: Business event definition.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_name
              - event_attributes
              - created_by
              properties:
                event_name:
                  type: string
                  description: This field contains the name of the business event.
                  example: NameOfOTTSeries
                event_attributes:
                  type: array
                  description: This field contains the event attributes of the business event being created.
                  items:
                    type: object
                    required:
                    - attribute_name
                    - attribute_data_type
                    properties:
                      attribute_name:
                        type: string
                        description: The name of the attribute.
                        example: season
                      attribute_data_type:
                        type: string
                        description: The data type of the attribute.
                        enum:
                        - string
                        - int
                        - float
                        - array
                        - date
                        example: string
                created_by:
                  type: string
                  format: email
                  description: The email address of the creator of the business event.
                  example: john.doe@example.com
            example:
              event_name: NameOfOTTSeries
              event_attributes:
              - attribute_name: season
                attribute_data_type: string
              - attribute_name: episodes
                attribute_data_type: int
              - attribute_name: cast
                attribute_data_type: array
              - attribute_name: released_on
                attribute_data_type: date
              - attribute_name: budget
                attribute_data_type: float
              created_by: john.doe@example.com
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The business event has been created
                  event_id:
                    type: string
                    description: Unique identifier for the created business event.
                    example: 64a40cff5547a6b2c5b14404
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                additionalFields:
                  summary: Additional Fields Present
                  value:
                    error:
                      code: 400 Bad Request
                      message: Additional fields are not allowed document schema for class BusinessEventCreateRequest:event_attribute
                      details:
                      - code: InvalidValue
                        target: event_attribute
                        message: Additional fields are not allowed document schema for class BusinessEventCreateRequest:event_attribute
                      request_id: 64a54b4b633fda13b668125d
                missingField:
                  summary: Missing Mandatory Field
                  value:
                    error:
                      code: 400 Bad Request
                      message: Bad request
                      details:
                      - code: MissingValue
                        target: created_by
                        message: 'created_by - Field is required but value is None : None'
                      request_id: 64a54b0f633fda13b6681259
                invalidDataType:
                  summary: Incorrect Data Type
                  value:
                    error:
                      code: 400 Bad Request
                      message: Bad request
                      details:
                      - code: MissingValue
                        target:
                        - brand
                        message: '[''brand''] - Wrong Attribute data type is passed : ''String'''
                      request_id: 64a54b6c633fda13b668125e
        '401':
          description: This response is returned when the authorization parameters are missing or incorrect in the HTTP Auth Header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                missingHeader:
                  summary: Missing Auth Header
                  value:
                    error:
                      code: 401 Authentication error
                      message: Authentication required
                      details:
                      - code: InvalidValue
                        target: Authorization
                        message:
                          code: MissingValue
                          target: Authorization
                          message: APP_ID and APP_SECRET_KEY is missing in Authorization Header.
                      request_id: 64a54b9d633fda13b6681261
                invalidAppId:
                  summary: Invalid App ID
                  value:
                    error:
                      code: 401 Authentication error
                      message: Authentication required
                      details:
                      - code: InvalidValue
                        target: APP_ID
                        message:
                        - code: InvalidValue
                          target: APP_ID
                          message: Invalid APP_ID is provided.
                      request_id: 64a54bfa633fda13b6681262
                invalidSecretKey:
                  summary: Invalid Secret Key
                  value:
                    error:
                      code: 401 Authentication error
                      message: Authentication required
                      details:
                      - code: InvalidValue
                        target: APP_SECRET_KEY
                        message:
                        - code: InvalidValue
                          target: APP_SECRET_KEY
                          message: Invalid APP_SECRET_KEY is provided.
                      request_id: 64a54c25633fda13b6681318
        '429':
          description: This response is returned when the number of requests has exceeded the rate limit.
          content:
            application/json:
              schema:
                type: object
              example:
                status: error
                data:
                  code: 429
                  title: rate limiter exception
                  description: Exceeded rate limit for this app
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                type: object
              example:
                title: Internal Server Error
                message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
  /business_event/trigger:
    post:
      tags:
      - Business Events
      summary: Trigger Business Event
      description: 'This API triggers a business event in MoEngage. You can set up campaigns to be executed when these events are triggered.

        '
      x-mint:
        content: '#### Rate Limit

          For Campaigns:

          - You can send a maximum of 200 triggers per day

          - You can send a maximum of 50 triggers per hour.


          For Flows:

          - You can trigger a maximum of 3 Business Trigger flows per hour.

          - You can trigger a maximum of 10 Business Trigger flows per day.

          '
      operationId: triggerBusinessEvent
      requestBody:
        description: Event to trigger.
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
              - event_name
              - event_attributes
              properties:
                event_name:
                  type: string
                  description: The name of the business event to be triggered.
                  example: Series_Name
                event_attributes:
                  type: object
                  description: 'This field contains the event attributes with which the business event will be triggered.


                    **Structure:** "event_attributes": { "attribute_name1": "<attribute value>", ... }


                    Every attribute contains the following information:

                    *attribute_name* - This field contains the name of the business event attribute for which the value is being sent in the request. The attribute_name is a String.


                    **Example:** "attribute_name": "season"

                    '
                  additionalProperties: true
                  example:
                    season: Season 1
                    episodes: 12
                    cast:
                    - John Doe
                    - Jane Doe
                    date: 11/11/2023
                triggered_by:
                  type: string
                  format: email
                  description: Information about who triggered the business event.
                  example: john.doe@example.com
            example:
              event_name: Series_Name
              event_attributes:
                season: Season 1
                episodes: 12
                cast:
                - John Doe
                - Jane Doe
                date: 11/11/2023
              triggered_by: john.doe@example.com
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  message:
                    type: string
                    example: The business event has been triggered
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                eventNotFound:
                  summary: Event does not exist
                  value:
                    error:
                      code: 400 Bad Request
                      message: Business event does not exists
                      details:
                      - code: InvalidValue
                        target: event_name
                        message: Business event does not exist
                      request_id: 64a54cf9633fda13b668132f
                wrongAttribute:
                  summary: Wrong Attribute
                  value:
                    error:
                      code: 400 Bad Request
                      message: Wrong business event attribute passed in api request
                      details:
                      - code: InvalidValue
                        target: rating1
                        message: Wrong business event attribute passed in api request
                      request_id: 64a54b0f633fda13b6681259
                noActiveCampaign:
                  summary: No active campaign found
                  value:
                    error:
                      code: 400 Bad Request
                      message: No active campaign found for business event name
                      details:
                      - code: InvalidValue
                        target: event_name
                        message: No active campaign found for business event name
                      request_id: 64a54dbf633fda13b668142d
                invalidEmail:
                  summary: Invalid Email
                  value:
                    error:
                      code: 400 Bad Request
                      message: Business event does not exists
                      details:
                      - code: MissingValue
                        target: triggered_by
                        message: 'triggered_by - Invalid email address : ''abc'''
                      request_id: 64a54dec633fda13b668142f
        '401':
          description: This response is returned when the authorization parameters are missing or incorrect in the HTTP Auth Header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401 Authentication error
                  message: Authentication required
                  details:
                  - code: InvalidValue
                    target: Authorization
                    message:
                      code: MissingValue
                      target: Authorization
                      message: APP_ID and APP_SECRET_KEY is missing in Authorization Header.
                  request_id: 64a54e0e633fda13b6681430
        '429':
          description: This response is returned when the number of requests has exceeded the rate limit.
          content:
            application/json:
              schema:
                type: object
              example:
                status: error
                data:
                  code: 429
                  title: rate limiter exception
                  description: Exceeded rate limit for this app
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                type: object
              example:
                title: Internal Server Error
                message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
  /business_event/search:
    post:
      tags:
      - Business Events
      summary: Search Business Events
      description: This API searches for business events by specifying their event IDs.
      x-mint:
        content: '#### Rate Limit

          The rate limit is 100 RPM.

          '
      operationId: searchBusinessEvents
      requestBody:
        description: Search criteria. At least one of event_ids or event_names should be provided.
        content:
          application/json:
            schema:
              type: object
              properties:
                event_ids:
                  type: array
                  items:
                    type: string
                  description: 'This field contains the list of event ids associated with the business events that need to be fetched.


                    **Structure:** "event_ids":  ["event_id1","event_id2","event_id3"]


                    *event_id*: The event id is the unique identifier for a business event and is generated by MoEngage at the time of business event creation. You must store and use this value while looking up a business event using the search API.

                    '
                  example:
                  - 6447b078712cd8c650074840
                event_names:
                  type: array
                  items:
                    type: string
                  description: 'This field contains the list of event names associated with the business events that need to be fetched.


                    **Structure:** "event_names":  ["event_name1","event_name2","event_name3"]


                    *event_name*: The event name is the name associated with the Business Event that is provided during the creation of the event.

                    '
                  example:
                  - NewMovies
            example:
              event_ids:
              - 6447b078712cd8c650074840
      responses:
        '200':
          description: This response is returned when the request is processed successfully.
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/BusinessEvent'
              example:
                data:
                - db_name: Sample_App
                  event_id: 647597767459c85d7d6d6dfd
                  event_name: NewMovies
                  event_attributes:
                  - attribute_name: MovieName
                    attribute_data_type: array
                  - attribute_name: rating
                    attribute_data_type: string
                  created_at: '2023-05-29T18:36:52.390000'
                  total_trigger: 0
                  users_in_segment: 0
                  usage_count: 0
                  created_by: john.doe@moengage.com
                  last_received_time: '2023-05-30T06:28:06.498000'
                  _id: 64a54500633fda13b6681163
        '400':
          description: This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 400 Bad Request
                  message: Additional fields are not allowed document schema for class BusinessEventSearchRequest:event_name
                  details:
                  - code: InvalidValue
                    target: event_name
                    message: Additional fields are not allowed document schema for class BusinessEventSearchRequest:event_name
                  request_id: 64a54e62633fda13b6681431
        '401':
          description: This response is returned when the authorization parameters are missing or incorrect in the HTTP Auth Header.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: 401 Authentication error
                  message: Authentication required
                  details:
                  - code: InvalidValue
                    target: Authorization
                    message:
                      code: MissingValue
                      target: Authorization
                      message: APP_ID and APP_SECRET_KEY is missing in Authorization Header.
                  request_id: 64a54e0e633fda13b6681430
        '429':
          description: This response is returned when the number of requests has exceeded the rate limit.
          content:
            application/json:
              schema:
                type: object
              example:
                status: error
                data:
                  code: 429
                  title: rate limiter exception
                  description: Exceeded rate limit for this app
        '500':
          description: This response is returned when the system runs into an unexpected error.
          content:
            application/json:
              schema:
                type: object
              example:
                title: Internal Server Error
                message: An unexpected error was encountered while processing this request. Please contact MoEngage Team
components:
  schemas:
    EventAttributeDefinition:
      type: object
      description: Definition of an attribute for a business event.
      required:
      - attribute_name
      - attribute_data_type
      properties:
        attribute_name:
          type: string
          description: The name of the attribute.
          example: season
        attribute_data_type:
          type: string
          description: The data type of the attribute.
          enum:
          - string
          - int
          - float
          - array
          - date
          example: string
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: This field contains the error code.
              example: 400 Bad Request
            message:
              type: string
              description: This field contains the error message.
              example: Bad request
            details:
              type: array
              description: This array contains the specifics and describes the error in detail.
              items:
                type: object
                properties:
                  code:
                    type: string
                    example: InvalidValue
                  target:
                    oneOf:
                    - type: string
                    - type: array
                      items:
                        type: string
                    example: event_name
                  message:
                    oneOf:
                    - type: string
                    - type: object
                    - type: array
                    example: Business event does not exist
            request_id:
              type: string
              description: This field contains the request ID of the failed request.
              example: 64a54cf9633fda13b668132f
    BusinessEvent:
      type: object
      description: A full business event object.
      properties:
        db_name:
          type: string
          description: Name of the database.
          example: Sample_App
        event_id:
          type: string
          description: Unique identifier for the business event.
          example: 647597767459c85d7d6d6dfd
        event_name:
          type: string
          description: Name of the business event.
          example: NewMovies
        event_attributes:
          type: array
          items:
            $ref: '#/components/schemas/EventAttributeDefinition'
        created_at:
          type: string
          format: date-time
          description: Timestamp of when the event was created.
        last_updated:
          type: string
          format: date-time
          description: Timestamp of when the event was last updated.
        total_trigger:
          type: integer
          description: Number of times the event has been triggered.
          example: 0
        total_sent_message:
          type: integer
          description: Number of campaign messages sent for this event.
        users_in_segment:
          type: integer
          description: Number of users in the segment.
          example: 0
        usage_count:
          type: integer
          example: 0
        created_by:
          type: string
          format: email
          description: Email of the event creator.
          example: john.doe@moengage.com
        last_received_time:
          type: string
          format: date-time
          description: Timestamp of when the event was last triggered.
        _id:
          type: string
          description: Internal database ID.
          example: 64a54500633fda13b6681163
  securitySchemes:
    basicAuth:
      type: http
      scheme: basic
      description: 'Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format ''username:password''.


        - **Username**: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at **Settings** > **Account** > **APIs** > **Workspace ID (earlier app id)**.

        - **Password**: Use your API Key, which you can find within the **Campaign report/Business events/Custom templates/Catalog API/Inform Report** tile.


        For more information on authentication and getting your credentials, refer [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).

        '