openapi: 3.0.3 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.' tags: - name: Business Events description: Manage and trigger business events. security: - basicAuth: [] 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": "", ... } 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: 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). 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 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 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