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

# API Documentation

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

The MoEngage REST APIs let you manage user data, campaigns, segments, content, and integrations without the dashboard. Every endpoint uses standard HTTP methods and JSON request and response bodies, and authenticates with an API key you create in the dashboard.

This reference covers the available API categories, along with the data centers, base URLs, authentication, rate limits, and error handling that apply across them.

## API Categories

<CardGroup cols={2}>
  <Card title="Data" icon="database" href="/docs/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="/docs/api/business-events/business-events-v5/business-events-v5-overview">
    Create and trigger business events to power automated campaigns.
  </Card>

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

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

  <Card title="Segments" icon="users" href="/docs/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="/docs/api/subscription-categories/subscription-categories-v5/subscription-categories-overview-v5">
    Manage email subscriptions and subscription category preferences.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/docs/api/analytics/analytics-overview">
    Access custom dashboards and fetch the analytics data behind their charts.
  </Card>

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

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

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

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

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

  <Card title="Message Archival" icon="box-archive" href="/docs/api/message-archival/message-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
* **Indonesia region**: Sign up with DC-06

<Note>
  DC-05 (Singapore) is not available for new sign-ups. Existing DC-05 workspaces remain operational and continue to use `https://api-05.moengage.com` for API requests. For data residency requirements in Singapore, contact your Customer Success Manager.
</Note>

<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

MoEngage API requests use Basic Authentication by default. Depending on the API group, a key can instead use OAuth 2.0 or AWS STS Auth:

* **OAuth 2.0**: Issues short-lived access tokens that you pass in the `Authorization` header of each request. For the token endpoints, the request format, and the token lifecycle, refer to [OAuth 2.0 Overview](/docs/api/oauth/oauth-overview).
* **AWS STS Auth**: Authorizes callers by their AWS assumed-role ARN instead of a shared secret. For the accepted ARN format and how to allowlist role ARNs on a key, refer to [AWS STS Auth](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard#aws-sts-auth).

You set the authentication type when you create the key. For the types each API group supports, refer to [API Key Dashboard](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard).

To authenticate using Basic Authentication, include a Base64-encoded string of your credentials in the Authorization header of every request. Basic Authentication encodes a 'username:password' string in Base64 and prefixes 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} # This header is mandatory for the File Import and Test Connection APIs. It is not required for API Endpoints under Data.
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**.

For creating, scoping, regenerating, and archiving keys, see [API Key Dashboard](/docs/user-guide/settings/account/api-and-api-keys/api-key-dashboard). To authenticate with OAuth 2.0 instead, see [OAuth 2.0 Overview](/docs/api/oauth/oauth-overview).

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

MoEngage enforces per-workspace rate limits and payload caps on its REST APIs. Requests that exceed a rate limit receive an `HTTP 429` response; oversized payloads receive `HTTP 413` (or `400`). Rate-limited responses include `x-ratelimit-limit`, `x-ratelimit-remaining`, and `x-ratelimit-reset` headers so you can track remaining capacity in real time.

For the full per-endpoint breakdown, covering rate limits, payload size caps, monitoring headers, and how to request an increase, see [Rate Limits](/docs/api/rate-limits).

***

## Error Handling

Most MoEngage APIs return errors in the standard format below.

### Standard Error Format

```json wrap theme={null}
{
  "status": "fail",
  "error": {
    "message": "The request parameters are invalid",
    "type": "Bad Request",
    "request_id": "abc123xyz"
  }
}
```

<Note>
  Newer v5 APIs, such as [Flows](/docs/api/flows/flows-overview), use a different error envelope: `{ response_id, error: { code, message, target, details } }`. Refer to the specific API's reference for its exact error shape.
</Note>

### 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` | List all recommendations |
| `GET` | `/recommendations/{recommendation_id}` | Get the details of a recommendation |
| `POST` | `/recommendations/{recommendation_id}/items` | Get recommended items for a user |

#### 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 |
| `GET` | `/v5/subscription-categories` | Get subscription categories (V5) |
| `GET` | `/v5/subscription-preferences` | Get subscription preferences (V5) |
| `PATCH` | `/v5/subscription-preferences` | Update subscription preferences (V5) |

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.