Data API helps in sending events and user details from your servers to MoEngage servers.
Data API is a collection of the following APIs
- User API
- Device API
- Event API
- Bulk Import API
Data API Endpoints
MoEngage supports multiple data centers with different dashboards and data API endpoints. When you sign up with MoEngage, you will be assigned a particular data center and the relevant dashboard is displayed. Use the data API endpoints associated with the data center.
For more information about your data center, contact [email protected]
You can find out which data center you are assigned to when you log in to the dashboard. The following table describes the dashboard URL and data API endpoint associated with the data center.
Two versions of the dashboard URL and data API endpoints are provided by MoEngage.
Data Centers and API Endpoints
New Data Center Name | New Dashboard URL | New Data API Endpoint | Old Data Center Name | Old Dashboard URL | Old Data API Endpoint |
---|---|---|---|---|---|
Data Center 1 | Default | ||||
Data Center 2 | EU | ||||
Data Center 3 | India |
Please note that we will continue to support both the old and new data API endpoints mentioned in the above table for foreseeable future but we recommend out customers to move to the new endpoints as soon as possible.
Syntax
New version
POST https://api-01.moengage.com/v1/
POST https://api-02.moengage.com/v1/
POST https://api-03.moengage.com/v1/
Old version
POST https://api.moengage.com/v1/
POST https://api-eu.moengage.com/v1/
POST https://api-serv3.moengage.com/v1/
Request Headers
Request headers are applicable to User, Device, Event, and Bulk Import APIs.
Header | Sample Value | Description |
---|---|---|
Authorization | {"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="} | Basic authentication is used for access control. |
Content-Type | {"Content-Type": "application/json"} | Set the Content-Type header to application/JSON for using the Data API. |
MOE-APPKEY | {"MOE-APPKEY": "APP ID"} | Set the MOE-APPKEY header available at Settings > App Settings > Account Settings > APP ID in the MoEngage App. |
Authentication
Basic authentication sends a Base64-encoded string containing username and password for all API requests.
Authentication is applicable to User, Device, Event, and Bulk Import APIs.
Username and password are available at Settings > APIs > DATA API Settings
Do the following when you are using the API for the first-time authentication:
1. Navigate to Settings > APIs > DATA API Settings
2. Click Generate Key
3. Save the details on the Data APIs settings page.
User name - DATA API ID
Password - DATA API KEY
Once you generate and save the Data API Key, please DO NOT generate a new key unless there is a security breach. Once you generate a different Data API key and save it, your existing data tracking will need to be updated as the authentication will start failing.
For example, basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. The string is passed in the authorization header as follows:
{"Authorization":"Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}


Authentication is performed using a client like Postman as follows:


Request Body
The maximum limit for the request body is 100KB.
The request body contains the mandatory field called customer_id. customer_id is the Unique Identifier set and passed on from MoEngage SDK as USER_ATTRIBUTE_UNIQUE_ID and is visible on the dashboard as ID.
customer_id is used to
* Identify or create a user in MoEngage
* Associate the events to the corresponding unique user profiles in MoEngage.
On receiving a Data API request in MoEngage, the customer_id is used to verify if the user exists in MoEngage. If the user does not exist, a new user is created with the attributes or events.
Allowed values of customer_id
Any string of more than one characters is allowed for customer_id except the following values - ['unknown', 'guest', 'null', '0', '1', 'true', 'false', 'user_attribute_unique_id', '(empty)', 'na', 'n/a', '', 'dummy_seller_code', 'user_id', 'id', 'customer_id', 'uid', 'userid', 'none', '-2', '-1', '2']
For example, a user created using the following request is visible in the dashboard user profile as displayed.
Request Body Example
Below is a sample request body for the user API
{
"type" : "customer",
"customer_id": "USERID1234",
"attributes": {
"first_name":"John",
"name":"John Smith",
"plan_expiry_date":"2020-05-31T00:00:00Z",
"super_user":true,
"user_persona":"browsers",
"platforms" : [{"platform":"ANDROID", "active":"true"}]
}
}
Dashboard User Profile
On sending data through the data API, it will be populated in the user profile as shown below -


Response
Response to the Data API is a JSON object.
On a successful data API request, you will receive the following response:
{"status":"success"}
On a failed data API request, you will receive the following response:
{
"status":"fail",
"error":{
"type": "TypeError",
"message":"expected string"
}
}
Response Codes
The following status codes and associated error messages are returned when the request results in a fatal error.
Error Code | Type | Message | Description |
---|---|---|---|
400 | Missing header value | The Content-Type Header is required | The header value for Content type is missing |
400 | Empty request body | A valid JSON document is required | The request body is empty |
400 | Malformed JSON | Could not decode the request body. The JSON was incorrect or not encoded as UTF-8. | The request JSON is not formed correctly |
400 | Blacklisted | Your account is blacklisted, Please contact MoEngage. | Your App is blacklisted in MoEngage |
400 | InvalidParams | given app_id is invalid. | The App Id is invalid |
400 | ParamsRequired | app_id is required in path/query params. | App Id is missing in the path or query params |
400 | Empty request body | A valid JSON document is required | The request body is empty. |
400 | Body type is not JSON | A valid JSON document is required. | String Payload |
400 | MissingAttributeError | {{key}} is expected to be {{datatype}} | The specified attributes are invalid |
401 | Authentication Required | Authentication Header Required | Authentication header is missing from the request |
401 | Authentication required | No identity information found | Authentication header is empty |
401 | Authentication required | Invalid identity information found | Failure to decode app_key and app_secret |
401 | Authentication required | APP_KEY missing in the authentication header | App_key is not present in the authentication header |
401 | Authentication required | APP_SECRET missing in the authentication header | App_secret os not present in the authentication header |
401 | Authentication required | App Secret key mismatch. Please login to the dashboard to verify key | App secret key is wrong |
401 | Authentication required | Invalid APP_ID used in Authentication Header | You have used an invalid APP Id in the authentication header |
403 | Account Suspended | Account Suspended | Your account is suspended |
403 | Account Temporarily Suspended | Account Temporarily Suspended | Your account is suspended temporarily. |
409 | Authentication Mismatch | App key mismatch in params and authentication | App_key in parameters and authentication does not match |
409 | Authentication required | App Secret key is not set. Please login to the dashboard to set a key | App Secret not set |
413 | Payload too large | The payload can not exceed 128KB | Request payload size is too large |
415 | Unsupported Media Type | Unsupported Media Type | Unsupported Media Type |
429 | Rate Limit Exceeded | Rate Limits for User / Event exceeded | You have exceeded the rate limits (number of users or events per minute) defined for your MoEngage account. |
500 | Server Error | Any other exception |
Limits
The Data API is designed to handle high volumes of data across our customer base. We enforce API limits to ensure responsible use of the API.
The following table describes the recommended rate limits of the Data APIs:
API Name | Rate Limit | Description |
---|---|---|
User | 1,000 users per min | A single API request contains one or more than one user updates. Maintain a rate limit of 1000 user updates per minute. |
Event | 10,000 events/min | A single API request contains one or more than one events. Maintain a rate limit of 10,000 events per minute. |
Bulk Import | 1,000 users/min and 10,000 events/min | A single bulk import API contains users, devices and events together. Send maximum of 1000 users and 10000 events per minute across all API requests. |
API Limits Breaching
Please note that on breaching the rate limits, your requests will be rejected with a response code of 429.
User API
User API helps add or update users and user properties in MoEngage. You can do the following:
- Create a new user
- Create new user property
- Update existing user properties of users
EndPoints
Data Center | New Endpoint | Old Endpoint |
---|---|---|
Data Center 1 (Default) | ||
Data Center 2 (EU) | ||
Data Center 3 (India) |
Syntax
New Version for different data centers
POST https://api-01.moengage.com/v1/customer/<APP ID>
POST https://api-02.moengage.com/v1/customer/<APP ID>
POST https://api-03.moengage.com/v1/customer/<APP ID>
Older Version for different data centers
POST https://api.moengage.com/v1/customer/<APP ID>
POST https://api-eu.moengage.com/v1/customer/<APP ID>
POST https://api-serv3.moengage.com/v1/customer/<APP ID>
Support for Old and New Endpoints
Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.
APP_ID
The APP_ID for your moengage account is available here: (Settings > App Settings > Account Settings > APP ID).
Request Body
A sample request body is described for user with unique id [email protected], where the following is set:
- Name
- John
- Active Platform
- Android
{
"type" : "customer",
"customer_id": "[email protected]",
"attributes": {
"name":"John",
"platforms" : [{"platform":"ANDROID", "active":"true"}]
}
}
Request Body Fields
Key | Datatype | Mandatory Field | Description |
---|---|---|---|
type | String | Yes | This is used to identify the type of request. |
customer_id | String | Yes | The unique identifier used to identify / create a user in MoEngage. Please refer this section for more information on customer_id. |
attributes | JSON Object | No | A dictionary containing user attributes to add / update in the user profile. |
platforms | List | No | List of dictionaries with the associated platforms out of ANDROID, iOS and web and their status. |
Standard User Attributes
The following standard user attributes are tracked for User API in MoEngage.
Key | Attribute Name on Dashboard | Datatype | Description |
---|---|---|---|
name | Name | String | Full name of the user. |
first_name | First Name | String | First name of the user. |
last_name | Last Name | String | Last name of the user. |
String | Email Address of the user. For example: [email protected] | ||
age | Age | Numeric | Age of the user |
gender | Gender | String | Gender of the user |
mobile | Mobile Number | String | Mobile Number of the user. For Example: 918888444411 |
moe_geo_location | Location | Array of [lat,lng] in double in the format {'lat': 12.11, 'lon': 123.122} | A sample value would be the location of the user. For example: {'lat': 12.11, 'lon': 123.122} |
source | Publisher Name | String | This is the Publisher Name of Install. . For example: Google Ads |
created_time | First Seen | Date | Time when the user was created. |
last_seen | Last Seen | Date | Last Seen Time of the user. |
transactions | Number of Conversions | Numeric | Total number of conversions made by the user in a lifetime. |
revenue | LTV | Numeric | Life Time Value of the user. |
moe_unsubscribe | Unsubscribe | Boolean | Email Unsubscribe Attribute. |
platforms | Not visible on dashboard. | List | Value are based on the active platforms of the user. |
For other attributes that are not part of the list, use the key-value pairs that you intend to use.
For example, to track custom attributes of different data types like string, numeric, boolean, and date, pass the following payload where points are a number, expiry_date is a date type attribute and super_user is a boolean attribute.
{
"type" : "customer",
"customer_id": "[email protected]",
"attributes": {
"points":20,
"expiry_date":"2020-05-31T03:47:35Z",
"super_user":true,
"user_persona":"browsers",
"platforms" : [{"platform":"ANDROID", "active":"true"}]
}
}
Reserved keywords for the user attribute name
"id", "_id", and "" keywords are blocked and do not use as user attribute names.
Different filters are available during the creation of campaigns and segments after an attribute is tracked in the required data type.
Examples
When an attribute is tracked in numeric data type, the following filters are displayed:


When an attribute is tracked as a string, the following filters are displayed:


When an attribute is tracked as a date attribute, the following filters are displayed:


For example, when an attribute is tracked as a boolean attribute, the following filters are displayed:


Device API
Device API helps to
- Create a new device profile
- Update profile data of an existing device.
Device API attributes include customer_id (Identifier of User), device_id (Identifier of Device), and other Device Attributes such as model, brand, os version, and so on.
Endpoints
Data Center | New Endpoint | Old Endpoint |
---|---|---|
Data Center 1 (Default) | ||
Data Center 2 (EU) | ||
Data Center 3 (India) |
Syntax
New Version for different data centers
POST https://api-01.moengage.com/v1/device/<APP ID>
POST https://api-02.moengage.com/v1/device/<APP ID>
POST https://api-03.moengage.com/v1/device/<APP ID>
Older version for different data centers
POST https://api.moengage.com/v1/device/<APP ID>
POST https://api-eu.moengage.com/v1/device/<APP ID>
POST https://api-serv3.moengage.com/v1/device/<APP ID>
Support for Old and New Endpoints
Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.
Request Body
A sample API request body is as follows:
{
"type": "device",
"customer_id": "[email protected]",
"device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
"attributes": {
"model": "iPhone",
"platform" : "iOS",
"push_preference" : "true",
"push_id" : "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I",
"app_version" : "10.1",
"os_version" : "2.5.4",
"active" : "true",
"created_time" : 143383676
}
}
Updating existing devices in MoEngage
For devices created by MoEngage SDK, device_id is internal and is not available for use externally.
You cannot update the device profiles created by MoEngage SDK. You can only create new device profiles and associate them to the appropriate user profile by
- Providing the correct customer_id
- Update the device profiles created by you by using the appropriate device_ids in the request.
Request Body Fields
Key | Datatype | Mandatory Field | Description |
---|---|---|---|
type | String | Yes | Identify the request type. |
customer_id | String | Yes | Identifier to identify or create a user in MoEngage. |
device_id | String | No | Identify specific devices in MoEngage. If this field is not present, MoEngage will create a new device. |
attributes | JSON Object | No | Dictionary containing device attributes to add or update in the device profile. |
platform | String | Yes | Platform is the type of device required to run push and in-app campaigns. Allowed values are ANDROID, iOS or web. |
push_id | String | Yes | Push Id or Push Token used to send a push notification to the device. |
Standard User Attributes
The following standard user attributes are tracked for Device API in MoEngage.
Key | Datatype | Description |
---|---|---|
model | String | Model of Device |
push_preference | Boolean | If push notifications are enabled for this device |
app_version | String | App version of the app currently present on this device. |
os_version | String | OS version of the device |
active | Boolean | If the app is currently active (installed) on this device or not. |
created_time | Numeric (Epoch time in seconds) | Time when this device was created. |
Using Device Attributes in MoEngage
Device attributes are only visible in the MoEngage Analytics module and not visible on the dashboard for Segmentation, Campaigns and User Profile.
For other attributes not part of the list, use the key-value pairs that you intend to use. For example, to set the brand attribute for the device to Apple
{
"type": "device",
"customer_id": "[email protected]",
"device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
"attributes": {
"brand": "Apple",
"platform": "iOS",
"push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
}
}
Reserved Keywords for Device Attribute names
"id", "_id", "" keywords are blocked and do not use in device attribute names.
Event API
Event API allows you to track the actions of a user.
Endpoints
Data Center | New Endpoint | Old Endpoint |
---|---|---|
Data Center 1 (Default) | ||
Data Center 2 (EU) | ||
Data Center 3 (India) |
Syntax
New Version for different data centers
POST https://api-01.moengage.com/v1/event/<APP ID>
POST https://api-02.moengage.com/v1/event/<APP ID>
POST https://api-03.moengage.com/v1/event/<APP ID>
Older Version for different data centers
POST https://api.moengage.com/v1/event/<APP ID>
POST https://api-eu.moengage.com/v1/event/<APP ID>
POST https://api-serv3.moengage.com/v1/event/<APP ID>
Support for Old and New Endpoints
Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.
Request Body
A sample API request is described:
{
"type": "event",
"customer_id": "[email protected]",
"device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
"actions": [{
"action": "Added to Cart",
"attributes": {
"product": "Mobile",
"color": "white",
"Brand": "Apple"
},
"platform": "iOS",
"app_version": "1.2.3",
"current_time": 1433837969,
"user_timezone_offset": 19800
},
{
"action": "Purchase",
"attributes": {
"product": "MacBook Air",
"Brand": "Apple"
},
"platform": "web",
"app_version": "1.2.3",
"current_time": 1433837969,
"user_timezone_offset": 19800
}
]
}
Request Body Fields
Key | Datatype | Required | Description |
---|---|---|---|
type | String | Yes | Identify the type of request. |
customer_id | String | Yes | Identifier to identify or create a user in MoEngage. |
device_id | String | No | device_id in event payload is optional. Default value is customer_id value. The value is used to map event to specific devices. |
actions | List | Yes | List of events to be tracked for the user. |
action | String | Yes | The name of the event to be tracked. |
attributes | JSON Object | No | Dictionary containing event attributes to track with the event. |
platform | String | No | Used to identify the platform on which the event happened. Allowed values are ANDROID, iOS, web or unknown. |
app_version | String | No | App Version of the app on which the event originated. |
user_time | Numeric(Epoch time in seconds) or String (ISO 8601 - ) | No | Local Time at which the event happened. |
current_time | Numeric (Epoch time in seconds) or String( ISO 8601) | No | UTC Time at which the event happened |
user_timezone_offset | Numeric | No | user_timezone_offset should have a value in seconds which can be between -54000 to 54000. For example, for IST (UTC+0530), "user_timezone_offset" will be 19800 |
Platform
Ensure that the platform value sent is Android, iOS or web. Platform value depends on the which platform the event was generated.
If you are unsure about the platform on which the event occured, send the value as unknown or do not send any value. Incorrect platform value leads to inconsistencies in platform level campaigns like Push and In-App.
Time of the event
MoEngage depends on current_time and user_timezone_offset for generating the local time at which the event occurred. The local time is displayed in the user profile on the dashboard.
- user_timezone_offset
- Used to determine the local timezone at which the event occurred.
- If the field is not present, then either one of the following is used: *The timezone present in user profile is considered. *The event occurred in UTC timezone.
- Format contains numeric value between -54000 to 54000. The value is the timezone offset of the local time from UTC in seconds.
- current_time
- Used to identify the UTC time at which the event occurred.
- If the field is not present, then the time at which the request was received is used as the current_time.
- Allowed formats for current_time are ISO 8601 , for example 2020-05-31T16:33:35Z or Epoch time in seconds, for example - 1590404615
Examples
The following example provides tracking of numeric, boolean, and date type event attributes.
Use the payload described, where the price is numeric, departure_date is a date type attribute and premium_seat is a boolean attribute.
{
"type": "event",
"customer_id": "[email protected]",
"actions": [{
"action": "Flight Bookoed",
"attributes": {
"price": 3999,
"departure_date": "2019-05-21T03:47:35Z",
"premium_seat": true
},
"platform": "iOS",
"app_version": "1.2.3",
"current_time": 1433837969,
"user_timezone_offset": 19800
}
]
}
Different attribute types allow you to use the relevant filters while creating segments. For example, when you track the above event, different filters corresponding to the data type of the event attributes are displayed as follows:


Reserved keywords for event and event attribute names
"id", "_id", "userId", "" keywords are blocked and do not use in event attribute names.
Bulk Import
Use the Bulk Import API to send, to MoEngage, in batch multiple user, device, and event requests using a single API request. You can send a batch request of a maximum of 100 kB in a single API call.
Endpoints
Data Center | New Endpoint | Old Endpoint |
---|---|---|
Data Center 1 (Default) | ||
Data Center 2 (EU) | ||
Data Center 3 (India) |
Syntax
New version for different data centers
POST https://api-01.moengage.com/v1/transition/<APP ID>
POST https://api-02.moengage.com/v1/transition/<APP ID>
POST https://api-03.moengage.com/v1/transition/<APP ID>
Older version for different data centers
POST https://api.moengage.com/v1/transition/<APP ID>
POST https://api-eu.moengage.com/v1/transition/<APP ID>
POST https://api-serv3.moengage.com/v1/transition/<APP ID>
Support for Old and New Endpoints
Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.
Request Body
A sample API request is as follows:
{
"type": "transition",
"elements": [{
"type": "customer",
"customer_id": "[email protected]",
"attributes": {
"name": "John",
"platforms": [{
"platform": "ANDROID",
"active": "true"
}]
}
},
{
"type": "device",
"customer_id": "[email protected]",
"device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
"attributes": {
"brand": "Apple",
"platform": "iOS",
"push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
}
},
{
"type": "event",
"customer_id": "[email protected]",
"device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
"actions": [{
"action": "Added to Cart",
"attributes": {
"product": "Mobile",
"color": "white",
"Brand": "Apple"
},
"platform": "iOS",
"app_version": "1.2.3",
"current_time": "2020-05-31T16:33:35Z",
"user_timezone_offset": 19800
},
{
"action": "Purchase",
"attributes": {
"product": "MacBook Air",
"Brand": "Apple"
},
"platform": "iOS",
"app_version": "1.2.3",
"current_time": 1590404615,
"user_timezone_offset": 19800
}
]
}
]
}
Request Body Fields
Key | Datatype | Required | Description |
---|---|---|---|
type | String | Yes | This is used to identify the type of request. |
element | List | Yes | List of data points (events, customers and devices) to track. |
API Validation for Bulk API
All bulk API requests return a 200 response code. Debugging should be done on the user profile on the dashboard.
Import APIs for Postman
We have made it easy for you to test the APIs.
Click on the following button to export our Data APIs into your Postman collections.
Updated about a month ago