API Overview - MoEngage

BetaWe 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 will be accessible until the transition is complete.

API Categories

Data

Create and update users, track events, manage devices, and import data in bulk.

Campaigns

Create and manage Push and Email campaigns programmatically.

Push

Send transactional and targeted push notifications to Android, iOS, and Web.

Inform

Send transactional alerts across SMS, Email, and Push channels.

Catalog

Manage product catalogs for recommendations and personalization.

Cards

Fetch and manage App Inbox cards for users.

Custom Segments

Create and manage file-based and filter-based user segments.

Business Events

Create and trigger business events to power automated campaigns.

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

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.

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.

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

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

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.

# Example: Encoding credentials
echo -n "YOUR_WORKSPACE_ID:YOUR_API_KEY" | base64

Getting Your Credentials

Log in to the MoEngage dashboard.
Navigate to Settings > Account > APIs.

Copy your Workspace ID and the relevant API Key.

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

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	Campaign report/Business events/Custom templates/Catalog API/Inform Report

Catalog	Campaign report/Business events/Custom templates/Catalog API/Inform Report

Personalize	Personalize

Quick Start

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

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": "[email protected]",
    "attributes": {
      "name": "John Doe",
      "u_em": "[email protected]",
      "platforms": [
        {
          "platform": "ANDROID",
          "active": "true"
        }
      ]
    }
  }'

Replace api-01 with your data center’s API host (e.g., api-02, api-03).

Expected Response:

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

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

{
  "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 and 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 and 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

Support

Need help with the API?

Help Center: help.moengage.com
Support: Contact your Customer Success Manager or reach out via the dashboard.

Getting Started

Endpoints

​API Categories

Data

Campaigns

Push

Inform

Catalog

Cards

Custom Segments

Business Events

​Data Centers

​Choosing a Data Center

​Base URL

​Authentication

​Required Headers

​Generating Credentials

​Getting Your Credentials

​API Keys by Feature

​Quick Start

​Rate Limits

​Rate Limit Response Headers

​Payload Size Limits

​Error Handling

​Standard Error Format

​HTTP Status Codes

​Key Endpoints Reference

​Data APIs

​Campaigns and Messaging

​Catalog

​Templates

​Content Blocks

​Segments and Audiences

​Business Events

​Live Activities (iOS)

​Support

API Categories

Data Centers

Choosing a Data Center

Base URL

Authentication

Required Headers

Generating Credentials

Getting Your Credentials

API Keys by Feature

Quick Start

Rate Limits

Rate Limit Response Headers

Payload Size Limits

Error Handling

Standard Error Format

HTTP Status Codes

Key Endpoints Reference

Data APIs

Campaigns and Messaging

Catalog

Templates

Content Blocks

Segments and Audiences

Business Events

Live Activities (iOS)

Support