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

# API Overview

> Your complete guide to integrating with MoEngage APIs. Send campaigns, manage users, track events, and power personalized customer engagement.

Welcome to the MoEngage API reference. Build powerful integrations to automate campaigns, sync user data, manage product catalogs, and deliver personalized experiences at scale.

## API Categories

<CardGroup cols={2}>
  <Card title="Data" icon="database" href="https://moengage.mintlify.app/api/data/data-overview">
    Create and update users, track events, manage devices, and import data in bulk.
  </Card>

  <Card title="Campaigns" icon="paper-plane" href="https://moengage.mintlify.app/api/campaigns/campaigns-overview">
    Create and manage Push and Email campaigns programmatically.
  </Card>

  <Card title="Push" icon="bell" href="https://moengage.mintlify.app/api/push/push-overview">
    Send transactional and targeted push notifications to Android, iOS, and Web.
  </Card>

  <Card title="Inform" icon="message" href="https://moengage.mintlify.app/api/inform/inform-overview">
    Send transactional alerts across SMS, Email, and Push channels.
  </Card>

  <Card title="Catalog" icon="box" href="https://moengage.mintlify.app/api/catalog/catalog-overview">
    Manage product catalogs for recommendations and personalization.
  </Card>

  <Card title="Cards" icon="rectangle-history" href="https://moengage.mintlify.app/api/cards/cards-overview">
    Fetch and manage App Inbox cards for users.
  </Card>

  <Card title="Custom Segments" icon="users" href="https://moengage.mintlify.app/api/custom-segments/custom-segments-overview">
    Create and manage file-based and filter-based user segments.
  </Card>

  <Card title="Business Events" icon="calendar-check" href="https://moengage.mintlify.app/api/business-events/business-events-overview">
    Create and trigger business events to power automated campaigns.
  </Card>
</CardGroup>

***

## Data Centers

MoEngage maintains multiple data centers. You are assigned to a specific data center when you sign up. You can identify your data center from your Dashboard URL.

| Data Center | Dashboard URL                       | REST API Host                 |
| ----------- | ----------------------------------- | ----------------------------- |
| DC-01       | `https://dashboard-01.moengage.com` | `https://api-01.moengage.com` |
| DC-02       | `https://dashboard-02.moengage.com` | `https://api-02.moengage.com` |
| DC-03       | `https://dashboard-03.moengage.com` | `https://api-03.moengage.com` |
| DC-04       | `https://dashboard-04.moengage.com` | `https://api-04.moengage.com` |
| DC-05       | `https://dashboard-05.moengage.com` | `https://api-05.moengage.com` |
| DC-06       | `https://dashboard-06.moengage.com` | `https://api-06.moengage.com` |

### Choosing a Data Center

If you have data privacy requirements to store user data in a specific geographical region:

* **US region**: Sign up with DC-01 or DC-04
* **EU region**: Sign up with DC-02
* **India region**: Sign up with DC-03
* **Singapore region**: Sign up with DC-05
* **Indonesia region**: Sign up with DC-06

<Warning>
  Once data is captured in a workspace, it cannot be migrated to a different data center. Always use the REST API endpoint matching your registered data center.
</Warning>

***

## Base URL

All API requests are made to:

```
https://api-{dc}.moengage.com
```

Replace `{dc}` with your data center number (e.g., `01`, `02`, `03`). You can identify your data center from your Dashboard URL.

<Note>
  Each API may have additional path segments (e.g., `/v1`, `/core-services/v1`). Refer to the specific API documentation for the complete endpoint path.
</Note>

***

## Authentication

All MoEngage APIs use **Basic Authentication** combined with a **MOE-APPKEY** header.

### Required Headers

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
Authorization: Basic {base64_encoded_credentials}
MOE-APPKEY: {your_workspace_id}
Content-Type: application/json
```

### Generating Credentials

The `Authorization` header value is a Base64 encoding of `workspace_id:api_key`.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
# Example: Encoding credentials
echo -n "YOUR_WORKSPACE_ID:YOUR_API_KEY" | base64
```

### Getting Your Credentials

1. Log in to the [MoEngage Dashboard](https://dashboard.moengage.com)
2. Navigate to **Settings** → **Account** → **APIs**
3. Copy your **Workspace ID** and the relevant **API Key**

### API Keys by Feature

Different APIs require different API keys from your dashboard:

| API         | API Key Location (Settings → Account → APIs)          |
| ----------- | ----------------------------------------------------- |
| Data        | Data API Key                                          |
| Push        | Push API Key                                          |
| Inform      | Inform API Key                                        |
| Campaigns   | Campaign report/Business events/Custom templates tile |
| Catalog     | Campaign report/Business events/Custom templates tile |
| Personalize | Personalize API Key                                   |

***

## Quick Start

Now that you have your credentials, make your first API request. This example creates a user profile using the Data API.

<CodeGroup>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl -X POST "https://api-01.moengage.com/v1/customer/YOUR_WORKSPACE_ID" \
    -H "Content-Type: application/json" \
    -u "YOUR_WORKSPACE_ID:YOUR_DATA_API_KEY" \
    -d '{
      "type": "customer",
      "customer_id": "john@example.com",
      "attributes": {
        "name": "John Doe",
        "u_em": "john@example.com",
        "platforms": [
          {
            "platform": "ANDROID",
            "active": "true"
          }
        ]
      }
    }'
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import requests
  import base64

  workspace_id = "YOUR_WORKSPACE_ID"
  api_key = "YOUR_DATA_API_KEY"

  credentials = base64.b64encode(f"{workspace_id}:{api_key}".encode()).decode()

  response = requests.post(
      f"https://api-01.moengage.com/v1/customer/{workspace_id}",
      headers={
          "Content-Type": "application/json",
          "Authorization": f"Basic {credentials}"
      },
      json={
          "type": "customer",
          "customer_id": "john@example.com",
          "attributes": {
              "name": "John Doe",
              "u_em": "john@example.com"
          }
      }
  )

  print(response.json())
  ```

  ```javascript JavaScript theme={"theme":{"light":"github-light","dark":"github-dark"}}
  const workspaceId = "YOUR_WORKSPACE_ID";
  const apiKey = "YOUR_DATA_API_KEY";
  const credentials = btoa(`${workspaceId}:${apiKey}`);

  fetch(`https://api-01.moengage.com/v1/customer/${workspaceId}`, {
    method: "POST",
    headers: {
      "Content-Type": "application/json",
      "Authorization": `Basic ${credentials}`
    },
    body: JSON.stringify({
      type: "customer",
      customer_id: "john@example.com",
      attributes: {
        name: "John Doe",
        u_em: "john@example.com"
      }
    })
  })
  .then(res => res.json())
  .then(data => console.log(data));
  ```
</CodeGroup>

<Info>
  Replace `api-01` with your data center's API host (e.g., `api-02`, `api-03`).
</Info>

**Expected Response:**

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "success",
  "message": "Your request has been accepted and will be processed soon."
}
```

***

## Rate Limits

Rate limits vary by API. Headers are included in responses to help you manage usage.

| API                          | Rate Limit                                             |
| ---------------------------- | ------------------------------------------------------ |
| **Campaigns API**            | 5 requests/min, 25 requests/hour, 100 requests/day     |
| **Catalog API**              | 100 requests/min or 1,000 requests/hour                |
| **Campaign Stats API**       | 100 requests/min/workspace                             |
| **Custom Segments (Filter)** | 50 requests/min, 200 requests/hour, 1,000 requests/day |
| **Custom Segments (File)**   | 10 operations/hour, 100 operations/day                 |

### Rate Limit Response Headers

```http theme={"theme":{"light":"github-light","dark":"github-dark"}}
x-ratelimit-limit: 100
x-ratelimit-remaining: 95
x-ratelimit-reset: 1699574400
```

### Payload Size Limits

| API                    | Max Payload Size |
| ---------------------- | ---------------- |
| Catalog API            | 5 MB             |
| Recommendations API    | 1 MB             |
| Bulk Import API        | 100 KB           |
| Custom Segments (File) | 150 MB per file  |

***

## Error Handling

All APIs return consistent error responses.

### Standard Error Format

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "status": "fail",
  "error": {
    "message": "The request parameters are invalid",
    "type": "Bad Request",
    "request_id": "abc123xyz"
  }
}
```

### HTTP Status Codes

| Code  | Description                        |
| ----- | ---------------------------------- |
| `200` | Success                            |
| `201` | Created                            |
| `202` | Accepted (async processing)        |
| `400` | Bad Request - Invalid parameters   |
| `401` | Unauthorized - Invalid credentials |
| `403` | Forbidden - Access denied          |
| `404` | Not Found - Resource doesn't exist |
| `409` | Conflict - Duplicate resource      |
| `413` | Payload Too Large                  |
| `429` | Rate Limit Exceeded                |
| `500` | Internal Server Error              |

***

## Key Endpoints Reference

### Data APIs

| Method | Endpoint                     | Description                  |
| ------ | ---------------------------- | ---------------------------- |
| `POST` | `/customer/{Workspace_ID}`   | Create or update user        |
| `POST` | `/customers/export`          | Get user details             |
| `POST` | `/customer/merge`            | Merge two users              |
| `POST` | `/customer/delete/bulk`      | Delete users in bulk         |
| `POST` | `/event/{Workspace_ID}`      | Track user events            |
| `POST` | `/device/{appId}`            | Create or update device      |
| `POST` | `/transition/{Workspace_ID}` | Bulk import users and events |

### Campaigns & Messaging

| Method | Endpoint                | Description                               |
| ------ | ----------------------- | ----------------------------------------- |
| `POST` | `/campaigns`            | Create Push or Email campaign             |
| `POST` | `/transaction/sendpush` | Send push notification                    |
| `POST` | `/alerts/send`          | Send transactional alert (SMS/Email/Push) |

### Catalog

| Method  | Endpoint                                  | Description            |
| ------- | ----------------------------------------- | ---------------------- |
| `POST`  | `/catalog`                                | Create catalog         |
| `PATCH` | `/catalog/{catalog_id}/attributes`        | Add catalog attributes |
| `POST`  | `/catalog/{catalog_id}/items`             | Ingest catalog items   |
| `PATCH` | `/catalog/{catalog_id}/items`             | Update catalog items   |
| `POST`  | `/catalog/{catalog_id}/items/bulk-delete` | Delete catalog items   |

### Templates

| Method | Endpoint                         | Description              |
| ------ | -------------------------------- | ------------------------ |
| `POST` | `/custom-templates/push`         | Create Push template     |
| `PUT`  | `/custom-templates/push`         | Update Push template     |
| `POST` | `/custom-templates/push/search`  | Search Push templates    |
| `POST` | `/custom-templates/sms`          | Create SMS template      |
| `PUT`  | `/custom-templates/sms`          | Update SMS template      |
| `POST` | `/custom-templates/sms/search`   | Search SMS templates     |
| `POST` | `/custom-templates/inapp`        | Create In-App template   |
| `PUT`  | `/custom-templates/inapp`        | Update In-App template   |
| `POST` | `/custom-templates/inapp/search` | Search In-App templates  |
| `POST` | `/custom-templates/osm`          | Create OSM template      |
| `PUT`  | `/custom-templates/osm`          | Update OSM template      |
| `POST` | `/custom-templates/osm/search`   | Search OSM templates     |
| `POST` | `/email-templates`               | Create Email template    |
| `PUT`  | `/email-templates/{template_id}` | Update Email template    |
| `GET`  | `/email-templates`               | Get all Email templates  |
| `GET`  | `/email-templates/{template_id}` | Get Email template by ID |

### Content Blocks

| Method | Endpoint                     | Description               |
| ------ | ---------------------------- | ------------------------- |
| `POST` | `/content-blocks`            | Create content block      |
| `PUT`  | `/content-blocks`            | Update content block      |
| `POST` | `/content-blocks/get-by-ids` | Get content blocks by IDs |
| `POST` | `/content-blocks/search`     | Search content blocks     |

### Segments & Audiences

| Method | Endpoint                           | Description           |
| ------ | ---------------------------------- | --------------------- |
| `POST` | `/v2/custom-segments/file-segment` | Create file segment   |
| `POST` | `/v3/custom-segments/`             | Create filter segment |
| `GET`  | `/v3/custom-segments`              | List custom segments  |
| `GET`  | `/v3/custom-segments/{id}`         | Get segment by ID     |

### Business Events

| Method | Endpoint                  | Description            |
| ------ | ------------------------- | ---------------------- |
| `POST` | `/business_event`         | Create business event  |
| `POST` | `/business_event/trigger` | Trigger business event |
| `POST` | `/business_event/search`  | Search business events |

### Live Activities (iOS)

| Method | Endpoint                          | Description          |
| ------ | --------------------------------- | -------------------- |
| `POST` | `/live-activity/broadcast/start`  | Start Live Activity  |
| `POST` | `/live-activity/broadcast/update` | Update Live Activity |
| `POST` | `/live-activity/broadcast/end`    | End Live Activity    |

***

## MCP Server

MoEngage provides a hosted [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that connects your AI-powered development tools directly to MoEngage documentation. Instead of searching the web, your AI assistant queries MoEngage docs in real time for accurate, up-to-date answers about APIs, SDKs, and platform features.

### Available tools

Your MCP server exposes the following tool:

| Tool             | Description                                                                                                                |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `SearchMoEngage` | Search across the MoEngage knowledge base to find documentation, code examples, API references, and implementation guides. |

### Connect to your AI tool

<Tabs>
  <Tab title="Cursor">
    <Steps>
      <Step title="Open MCP settings">
        Use **Cmd + Shift + P** (macOS) or **Ctrl + Shift + P** (Windows/Linux) to open the command palette, then search for **"Open MCP settings"**. This opens the `mcp.json` file.
      </Step>

      <Step title="Add the MoEngage MCP server">
        Add the following configuration to `mcp.json`:

        ```json mcp.json theme={"theme":{"light":"github-light","dark":"github-dark"}}
        {
          "mcpServers": {
            "MoEngage": {
              "url": "https://www.moengage.com/docs/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Restart and verify">
        Restart Cursor, then ask the AI assistant a question about MoEngage. You should see the `SearchMoEngage` tool listed as available.

        <Check>
          In Cursor's chat, ask "What tools do you have available?" and confirm the MoEngage MCP server appears.
        </Check>
      </Step>
    </Steps>
  </Tab>

  <Tab title="VS Code">
    <Steps>
      <Step title="Create the MCP config file">
        Create a `.vscode/mcp.json` file in your project root and add:

        ```json mcp.json theme={"theme":{"light":"github-light","dark":"github-dark"}}
        {
          "servers": {
            "MoEngage": {
              "type": "http",
              "url": "https://www.moengage.com/docs/mcp"
            }
          }
        }
        ```
      </Step>

      <Step title="Restart and verify">
        Restart VS Code. The MoEngage MCP server is now available to Copilot Chat.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude">
    <Steps>
      <Step title="Open Claude settings">
        Navigate to the [Connectors](https://claude.ai/settings/connectors) page in your Claude settings.
      </Step>

      <Step title="Add the MoEngage MCP server">
        1. In a chat, select the attachments button (the plus icon).
        2. Select **Add**.
        3. Enter **MoEngage** as the name and `https://www.moengage.com/docs/mcp` as the URL.
        4. Select **Add custom connector**.
      </Step>

      <Step title="Use in conversation">
        Ask Claude any question about MoEngage. Claude automatically searches the documentation when relevant.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Claude Code">
    Run the following command to add the MoEngage MCP server:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    claude mcp add --transport http MoEngage https://www.moengage.com/docs/mcp
    ```

    Verify the connection:

    ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
    claude mcp list
    ```
  </Tab>
</Tabs>

<Tip>
  You can skip manual setup by using the contextual menu on any MoEngage documentation page. Select **Connect to Cursor** or **Connect to VS Code** to install automatically, or copy the install command:

  ```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
  npx add-mcp MoEngage https://www.moengage.com/docs/mcp
  ```
</Tip>

<Note>
  The MCP server is available for public documentation only. Rate limits apply: 200 requests per hour per user and 1,000 requests per hour across all users.
</Note>

***

## Support

Need help with the API?

* **Help Center**: [help.moengage.com](https://help.moengage.com/hc/en-us)
* **Support**: Contact your Customer Success Manager or reach out via the dashboard