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

# API Overview

> 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 icon="database" href="/api/data/data-overview" title="Data">
    Create and update users, track events, manage devices, and import data in bulk.
  </Card>

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

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

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

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

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

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

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

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

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

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

  <Card icon="box-archive" href="/api/message-archival/messaage-archival-overview" title="Message Archival">
    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` |

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

### 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-partner-guide/XNC4qACqVHFkhQIR/images/api-dashboard.png?fit=max&auto=format&n=XNC4qACqVHFkhQIR&q=85&s=f95e77c7f73cfce8c287bf0c88a2c6e3" 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-partner-guide/XNC4qACqVHFkhQIR/images/authorization.png?fit=max&auto=format&n=XNC4qACqVHFkhQIR&q=85&s=b17f2129200632bf9d3d706bd5c988fd" 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?

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