Data API

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 support@moengage.com.

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 http://dashboard-01.moengage.com/ https://api-01.moengage.com/v1/ Default https://app.
moengage.com/
https://api.
moengage.com
Data Center 2 http://dashboard-02.moengage.com/ https://api-02.moengage.com/v1/ EU https://app-eu.
moengage.com/
https://api-eu.
moengage.com
Data Center 3 http://dashboard-03.moengage.com/ https://api-03.moengage.com/v1/ India https://app-serv3.
moengage.com/
https://api-serv3.
moengage.com

Syntax

New version

Text
POST https://api-01.moengage.com/v1/
POST https://api-02.moengage.com/v1/
POST https://api-03.moengage.com/v1/

Old version

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

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 SettingsDo the following when you are using the API for the first-time authentication:

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.
  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="}

d205ad9-B33zNd8vQFCkugDwITCz_Screen_Shot_2016-06-10_at_6.28.23_pm.png

Authentication is performed using a client like Postman as follows:

f0c37fd-postman_new_sample.png

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

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

2ffadbb-Screen_Shot_2020-05-25_at_5.00.59_PM.png

Response

Response to the Data API is a JSON object.

On a successful data API request, you will receive the following response:

JSON
{"status":"success"}

On a failed data API request, you will receive the following response:

JSON
{
  "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 update. 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 event. 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) https://api-01.moengage.com/v1/customer/ https://api.moengage.com/v1/customer/
Data Center 2 (EU) https://api-02.moengage.com/v1/customer/ https://api-eu.moengage.com/v1/customer/
Data Center 3 (India) https://api-03.moengage.com/v1/customer/ https://api-serv3.moengage.com/v1/customer/

Syntax

New Version for different data centers

Text
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

Text
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 the user with unique id john@example.com, where the following is set:

Name
John
Active Platform
Android
JSON
{
"type" : "customer",
"customer_id": "john@example.com",
"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.
email Email String Email Address of the user. For example: john@example.com
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.
Information in ISO 8601 format.
For example: 2019-05-21T03:47:35Z
last_seen Last Seen Date Last Seen Time of the user.
Information in ISO 8601 format.
For example 2020-05-01T03:52:35Z
transactions Number of Conversions Numeric A 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.
Emails are not sent to the user when the set value is true.
platforms Not visible on the dashboard. List Value is based on the active platforms of the user.
For example: [{"platform":"ANDROID", "active":"true"},{"platform":"IOS", "active":"true"}]

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.

JSON
{
"type" : "customer",
"customer_id": "john@example.com",
"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

The APP_ID for your moengage account is available here: (Settings > App Settings > Account Settings > APP ID).

Different filters are available during the creation of campaigns and segments after an attribute is tracked in the required data type.

 

Reserved keywords for the user attribute name

"id", "_id", and "" keywords are blocked and do not use as user attribute names.

Examples

When an attribute is tracked in numeric data type, the following filters are displayed:

48876a4-Screen_Shot_2020-05-21_at_10.53.03_AM.png

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

321c11b-Screen_Shot_2020-05-22_at_10.52.13_AM.png

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

a7c8743-Screen_Shot_2020-05-21_at_10.52.49_AM.png

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

af52326-Screen_Shot_2020-05-21_at_10.53.46_AM.png

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) https://api-01.moengage.com/v1/device/ https://api.moengage.com/v1/device/
Data Center 2 (EU) https://api-02.moengage.com/v1/device/ https://api-eu.moengage.com/v1/device/
Data Center 3 (India) https://api-03.moengage.com/v1/device/ https://api-serv3.moengage.com/v1/device/

Syntax

New Version for different data centers

Text
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

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

JSON
{
  "type": "device",
  "customer_id": "john@example.com",
  "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

JSON
{
  "type": "device",
  "customer_id": "john@example.com",
  "device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
  "attributes": {
    "brand": "Apple",
    "platform": "iOS",
    "push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
  }
}
 

Reserved keywords for the user attribute name

"id", "_id", and "" keywords are blocked and do not use as user 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) https://api-01.moengage.com/v1/event/ https://api.moengage.com/v1/event/
Data Center 2 (EU) https://api-02.moengage.com/v1/event/ https://api-eu.moengage.com/v1/event/
Data Center 3 (India) https://api-03.moengage.com/v1/event/ https://api-serv3.moengage.com/v1/event/

Syntax

New Version for different data centers

Text
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

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

JSON
{
	"type": "event",
	"customer_id": "john@example.com",
	"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.

JSON
{
	"type": "event",
	"customer_id": "john@example.com",
	"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:

2f684d9-Screen_Shot_2020-05-22_at_10.54.15_AM.png

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) https://api-01.moengage.com/v1/transition/ https://api.moengage.com/v1/transition/
Data Center 2 (EU) https://api-02.moengage.com/v1/transition/ https://api-eu.moengage.com/v1/transition/
Data Center 3 (India) https://api-03.moengage.com/v1/transition/ https://api-serv3.moengage.com/v1/transition/

Syntax

New Version for different data centers

Text
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

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

JSON
{
	"type": "transition",
	"elements": [{
			"type": "customer",
			"customer_id": "john@example.com",
			"attributes": {
				"name": "John",
				"platforms": [{
					"platform": "ANDROID",
					"active": "true"
				}]
			}
		},
		{
			"type": "device",
			"customer_id": "john@example.com",
			"device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
			"attributes": {
				"brand": "Apple",
				"platform": "iOS",
				"push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
			}
		},
		{
			"type": "event",
			"customer_id": "john@example.com",
			"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 here to export our Data APIs into your Postman collections.

 
Was this article helpful?
0 out of 0 found this helpful