> ## Documentation Index
> Fetch the complete documentation index at: https://moengage.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Business Events API (V5): Overview

> Trigger real-time business events through the unified MoEngage gateway, and look up the events registered in your workspace.

The MoEngage Business Events API (V5) lets you fire a business event that is already registered in your workspace — such as a flight delay, a price drop on a watched item, or the release of a new OTT series episode. Firing the event enqueues every active campaign and flow attached to it for delivery, so you can automate high-context communication based on external data points rather than just user behavior. The V5 endpoints also let you look up the business events that exist in your workspace.

These endpoints are served through the unified MoEngage gateway behind a versioned `{response_id, type, data}` envelope. To create a new business event, use the [Business Events (Legacy)](/docs/api/business-events/business-events-legacy/business-events-overview) API — that operation has not moved to V5 yet.

## Endpoints

The Business Events API (V5) is a collection of the following endpoints:

* [Trigger Business Event (V5)](/docs/api/business-events/trigger-business-event-v5): Fire a registered business event to enqueue its attached campaigns and flows.
* [List Business Events](/docs/api/business-events/list-business-events): List all business events in the workspace, or look up a single one by name or ID. Returns campaign and trigger counts, and supports cursor-based pagination.
* [Search Business Events (V5)](/docs/api/business-events/search-business-events-v5): List all business events, or look up several at once by names or IDs. Returns the same fields as List Business Events and supports cursor-based pagination.

## Authentication

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). Find it in the MoEngage dashboard at **Settings** > **Account** > **API keys**.
* **Password**: Use an API key from **Settings** > **Account** > **API keys**.

Refer to [API Key Dashboard](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard) for details on creating and managing API keys.

## FAQs

### Trigger Business Events

<AccordionGroup>
  <Accordion title="Do I need to pass all event attributes when triggering?">
    No. It isn't mandatory to send every attribute defined on the business event. Only include the attributes required for the personalization used by your campaigns and flows.
  </Accordion>

  <Accordion title="What happens if I trigger an event that doesn't exist?">
    The event name is validated against the events registered in your workspace. Make sure `event_name` matches an event already created via the [Create Business Event](/docs/api/business-events/create-business-event) API before triggering it.
  </Accordion>

  <Accordion title="What does triggered_status mean?">
    `triggered_status` summarizes the outcome of the trigger: `SUCCESS` (every attached campaign or flow was reserved), `PARTIAL_SUCCESS` (at least one reserved, at least one skipped by quota), or `FAILURE` (nothing reserved — either all were skipped by quota, or the event has no active campaigns or flows attached).
  </Accordion>

  <Accordion title="How do I know which campaigns or flows were actually triggered?">
    Check `triggered_campaign_ids` and `triggered_flow_ids` in the response `data` object — these list the IDs that were reserved for this firing. `failed_campaign_ids` and `failed_flow_ids` list anything skipped due to quota.
  </Accordion>

  <Accordion title="How do I verify a campaign received the trigger on the dashboard?">
    Navigate to **Engage -> Campaigns** on the MoEngage Dashboard and search for the campaign associated with your business event to view real-time analytics and trigger counts.
  </Accordion>
</AccordionGroup>

### Look Up Business Events

<AccordionGroup>
  <Accordion title="When should I use List Business Events instead of Search Business Events (V5)?">
    Use [List Business Events](/docs/api/business-events/list-business-events) to browse everything, or to look up one event by an exact `name` or `id` passed as query parameters. Use [Search Business Events (V5)](/docs/api/business-events/search-business-events-v5) to look up several events at once, since `filters.names` and `filters.ids` accept arrays. Both return the same fields and list everything when you supply no filter.
  </Accordion>

  <Accordion title="Can I combine names and ids in one search?">
    No. Provide either `filters.names` or `filters.ids`, not both. Supplying both returns a `400` error. The same rule applies to the `name` and `id` query parameters on List Business Events.
  </Accordion>

  <Accordion title="How do I page through results?">
    Both endpoints return at most 20 events per page. When `pagination.has_more` is `true`, pass `pagination.next_cursor` back as `cursor` to fetch the next page. Treat the cursor as opaque — do not decode or modify it.
  </Accordion>

  <Accordion title="Why do the V5 attribute data types differ from the legacy ones?">
    The V5 endpoints report attribute types as `string`, `number`, `boolean`, or `datetime`. The legacy [Create Business Event](/docs/api/business-events/create-business-event) API accepts `string`, `int`, `float`, `array`, and `date`. Map between the two when you move an integration to V5.
  </Accordion>

  <Accordion title="What is the difference between campaign_count and trigger_count?">
    `trigger_count` is the total number of times the event has been triggered. `campaign_count` is the cumulative number of child campaigns those triggers have launched across all firings.
  </Accordion>
</AccordionGroup>

## Postman Collection

Test these endpoints using our pre-configured Postman collection: [View MoEngage Business Events Collection](https://www.postman.com/moengage-dev/api-docs/collection/k48uulb/moengage-business-events-api-v5?action=share\&source=copy-link\&creator=3486165).