> ## 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.

# Introduction

> Explore MoEngage REST APIs for managing user data, campaigns, segments, templates, and integrations.

<Note>
  **Beta**

  We are refining the new API docs. While exploring them, you may encounter minor issues. We appreciate your patience as we finalize the content.

  The [existing API docs](https://developers.moengage.com/hc/en-us/categories/4404541620756-API) will be accessible until the transition is complete.
</Note>

## API Categories

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

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

  <Card title="Content" icon="file-lines" href="/api/in-app-templates/in-app-templates-overview">
    Manage templates, content blocks, recommendations, coupons, and catalogs.
  </Card>

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

  <Card title="Segments" icon="users" href="/api/custom-segments/custom-segments-overview">
    Create and manage file-based, filter-based, and cohort-synced user segments.
  </Card>

  <Card title="Subscriptions" icon="envelope-circle-check" href="/api/email-subscription/email-subscription-overview">
    Manage email subscriptions and subscription category preferences.
  </Card>

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

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

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

  <Card title="Live Activities" icon="circle-play" href="/api/live-activities/live-activities-overview">
    Start, update, and end iOS Live Activities via broadcast.
  </Card>

  <Card title="Personalize" icon="bullseye-arrow" href="/api/personalize-experience/personalize-overview">
    Fetch and manage personalized experiences for users.
  </Card>

  <Card title="Message Archival" icon="box-archive" href="/api/message-archival/messaage-archival-overview">
    View and retrieve archived messages.
  </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`  |
| DC-101      | `https://dashboard-101.moengage.com` | `https://api-101.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>
  After 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:

```text theme={null}
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 API requests require Basic Authentication. To authenticate, you must include a Base64-encoded string of your credentials in the Authorization header of every request. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

`{"Authorization: Basic Base64_ENCODED_WORKSPACEID_APIKEY=="}`

### Required Headers

```http theme={null}
Authorization: Basic {base64_encoded_credentials}
MOE-APPKEY: {your_workspace_id}
Content-Type: application/json
```

<Note>
  The `MOE-APPKEY` header (set to your Workspace ID) is required only for File Import APIs and the Test Connection API. It is not required for core Data APIs such as Track User, Get User, Track Event, Merge User, Delete User, and Track Device.
</Note>

### Generating Credentials

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

```bash theme={null}
# 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**.

<img src="https://mintcdn.com/moengage/qngr-kol4lD0Wo9q/images/api-dashboard.png?fit=max&auto=format&n=qngr-kol4lD0Wo9q&q=85&s=ed8d5d34466e7f26b62f4951f6122c17" alt="api-dashboard" width="3162" height="1382" data-path="images/api-dashboard.png" />

3. Copy your **Workspace ID** and the relevant **API Key**.

You can perform authentication using a client like Postman as follows:

<img src="https://mintcdn.com/moengage/aW3ByCohh6fhT6FX/images/authorization.png?fit=max&auto=format&n=aW3ByCohh6fhT6FX&q=85&s=3f158e56df4ef3b38130910c07a1469b" alt="Authorization" width="2030" height="666" data-path="images/authorization.png" />

### API Keys by Feature

Different APIs require different API keys from your dashboard:

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

## 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={null}
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 wrap theme={null}
{
  "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

| 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`                   | Delete users in bulk     |
| `POST` | `/event/{Workspace_ID}`              | Track user events        |
| `POST` | `/transition/{Workspace_ID}`         | Bulk import              |
| `POST` | `/device/{app_id}`                   | Create or update device  |
| `POST` | `/devices/manage`                    | Manage devices           |
| `POST` | `/fileimports/trigger/{schedule_id}` | Trigger file import      |
| `POST` | `/fileimports/import/status`         | Get import status        |
| `GET`  | `/installInfo`                       | Get install info         |
| `POST` | `/integrations/authentication`       | Validate authentication  |
| `POST` | `/opengdpr_requests/{appId}`         | Create GDPR/CCPA request |

### 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 |

### Content

#### Templates

| Method | Endpoint                         | Description              |
| ------ | -------------------------------- | ------------------------ |
| `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` | `/custom-templates/sms`          | Create SMS template      |
| `PUT`  | `/custom-templates/sms`          | Update SMS template      |
| `POST` | `/custom-templates/sms/search`   | Search SMS templates     |
| `POST` | `/email-templates`               | Create Email template    |
| `GET`  | `/email-templates`               | Get all Email templates  |
| `GET`  | `/email-templates/{id}`          | Get Email template by ID |
| `PUT`  | `/email-templates/{id}`          | Update Email template    |
| `POST` | `/custom-templates/email`        | Create Email template V2 |
| `PUT`  | `/custom-templates/email`        | Update Email template V2 |
| `POST` | `/custom-templates/push`         | Create Push template     |
| `PUT`  | `/custom-templates/push`         | Update Push template     |
| `POST` | `/custom-templates/push/search`  | Search Push templates    |

#### 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     |

#### Recommendations

| Method | Endpoint                                      | Description              |
| ------ | --------------------------------------------- | ------------------------ |
| `GET`  | `/recommendations/{recommendations_id}`       | Get recommendations      |
| `POST` | `/recommendations/{recommendations_id}/items` | Get recommendation items |

#### Coupons

| Method   | Endpoint                                               | Description          |
| -------- | ------------------------------------------------------ | -------------------- |
| `POST`   | `/coupon-list`                                         | Create coupon list   |
| `GET`    | `/coupon-list`                                         | List coupon lists    |
| `GET`    | `/coupon-list/{coupon_list_id}`                        | Get coupon list      |
| `PATCH`  | `/coupon-list/{coupon_list_id}`                        | Update coupon list   |
| `PUT`    | `/coupon-list/{coupon_list_id}/activate`               | Activate coupon list |
| `PUT`    | `/coupon-list/{coupon_list_id}/archive`                | Archive coupon list  |
| `POST`   | `/coupon-list/{coupon_list_id}/files`                  | Upload coupon file   |
| `GET`    | `/coupon-list/{coupon_list_id}/files`                  | List coupon files    |
| `GET`    | `/coupon-list/{coupon_list_id}/files/{coupon_file_id}` | Get coupon file      |
| `DELETE` | `/coupon-list/{coupon_list_id}/files/{coupon_file_id}` | Delete coupon file   |
| `POST`   | `/coupon-list/{coupon_list_id}/usage-report`           | Get usage report     |

#### Catalog

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

### Campaigns

| Method  | Endpoint                                         | Description              |
| ------- | ------------------------------------------------ | ------------------------ |
| `POST`  | `/campaigns`                                     | Create campaign          |
| `PATCH` | `/campaigns/{campaign_id}`                       | Update campaign          |
| `POST`  | `/campaigns/search`                              | Search campaigns         |
| `POST`  | `/campaigns/test`                                | Test campaign            |
| `POST`  | `/personalization/preview`                       | Preview personalization  |
| `POST`  | `/campaigns/meta`                                | Get campaign metadata    |
| `POST`  | `/campaigns/status`                              | Get campaign status      |
| `POST`  | `/campaigns/{parent_campaign_id}/executions`     | Get campaign executions  |
| `POST`  | `/core-services/v1/campaign-stats`               | Get campaign stats       |
| `GET`   | `/campaign_reports/rest_api/{APP_ID}/{FILENAME}` | Download campaign report |

### Segments

| Method  | Endpoint                                        | Description               |
| ------- | ----------------------------------------------- | ------------------------- |
| `POST`  | `/v2/custom-segments/file-segment`              | Create file segment       |
| `PUT`   | `/v2/custom-segments/file-segment/add-users`    | Add users to segment      |
| `PUT`   | `/v2/custom-segments/file-segment/remove-users` | Remove users from segment |
| `PUT`   | `/v2/custom-segments/file-segment/replace`      | Replace segment users     |
| `GET`   | `/v3/custom-segments`                           | List filter segments      |
| `POST`  | `/v3/custom-segments`                           | Create filter segment     |
| `GET`   | `/v3/custom-segments/{id}`                      | Get segment by ID         |
| `PATCH` | `/v3/custom-segments/{id}`                      | Update filter segment     |
| `POST`  | `/v1/integrations/cohortsync`                   | Sync cohort audience      |
| `PATCH` | `/v2/custom-segments/archive`                   | Archive segment           |
| `PATCH` | `/v2/custom-segments/unarchive`                 | Unarchive segment         |

### Subscriptions

| Method | Endpoint                                   | Description                     |
| ------ | ------------------------------------------ | ------------------------------- |
| `POST` | `/emails/v1.0/bulk-resubscribe`            | Bulk resubscribe emails         |
| `PUT`  | `/v1.0/opt-in-management/user-preferences` | Update opt-in preferences       |
| `GET`  | `/category-subscription/user-preferences`  | Get subscription preferences    |
| `PUT`  | `/category-subscription/user-preferences`  | Update subscription preferences |
| `POST` | `/category-subscription/user-preferences`  | Create subscription preferences |

### Push

| Method | Endpoint                | Description            |
| ------ | ----------------------- | ---------------------- |
| `POST` | `/transaction/sendpush` | Send push notification |

### Cards

| Method   | Endpoint        | Description  |
| -------- | --------------- | ------------ |
| `POST`   | `/cards/fetch`  | Fetch cards  |
| `DELETE` | `/cards/delete` | Delete cards |

### Inform

| Method | Endpoint       | Description                               |
| ------ | -------------- | ----------------------------------------- |
| `POST` | `/alerts/send` | Send transactional alert (SMS/Email/Push) |

### Live Activities

| 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    |

### Personalize

| Method | Endpoint                | Description             |
| ------ | ----------------------- | ----------------------- |
| `POST` | `/experiences/fetch`    | Fetch experiences       |
| `GET`  | `/experiences/metadata` | Get experience metadata |
| `POST` | `/experiences/events`   | Track experience events |

### Message Archival

| Method | Endpoint         | Description            |
| ------ | ---------------- | ---------------------- |
| `POST` | `/archival/view` | View archived messages |

***

## Support

Need help with the API?

* **Support**: Contact your Customer Success Manager or [raise a support ticket](https://www.moengage.com/docs/user-guide/contact-support/raise-a-support-ticket-through-moengage-dashboard).