MoEngage Docs

Data APIs

Data APIs are used to send user data (user properties and events) from your servers to MoEngage.

List of APIs

See the below table for a list of MoEngage APIs.

For our customers in EU Region, please navigate to this table - List of EU APIs.

API Name
Details
Endpoint

User

Use this API to send user properties.

Event

Use this API to send events.

Device

Use this API to send device properties.

Bulk Import

User this API to import data in bulk.

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

Note: We have updated the List of APIs on 4th December 2018 but we are continuing to support the older APIs as of now. The older APIs listed below will be deprecated soon. We strongly recommend all MoEngage users to migrate to the new APIs listed in the previous table.

API Name
Details
Endpoint

User

Use this API to send user properties.

Event

Use this API to send events.

Device

Use this API to send device properties.

Bulk Import

User this API to import data in bulk.

If you are using the older APIs, app_id is a required param
app_id: Get the APP ID from the MoEngage dashboard under following path: (Settings > App Settings > Account Settings > APP ID).

List of APIs for EU Region

The below table lists the APIs available for EU Region -

API Name
Details
Endpoint

User

Use this API to send user properties.

Event

Use this API to send events.

Device

Use this API to send device properties.

Bulk Import

User this API to import data in bulk.

Please note that we no longer need the app_id to be passed as a parameter in our EU APIs. This was required earlier. The APIs will not break irrespective of whether app_id is present as a parameter or not.

app_id: Get the APP ID from the MoEngage dashboard under following path: (Settings > App Settings > Account Settings > APP ID).

Required Headers

Authentication

Data APIs use Basic authentication to control access to your data.

Basic authentication sends a Base64-encoded string that contains a username and password for your API requests. username and password are available under following path: (Settings > APIs > DATA API Settings) as shown below.

For first time, hit the Generate Key and then save on Data APIs settings page.
User name - DATA API ID
Password - DATA API KEY

Basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. This is passed in the authorization header as follows
{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

To send a request using a client (as Postman), Authentication can be done in following way:

Content-Type Header

To send data to Data APIs, Content-Type header must be set to 'application/json' as follows
{"Content-Type": "application/json"}

MOE-APPKEY Header

To send data via Data APIs, MOE-APPKEY header must be set to <APP ID> which is available here: (Settings > App Settings > Account Settings > APP ID).

Request body

There is a max limit of 100kb per request.

Response

Response will be a json object, on a sucessful call you will receive response as

{"status":"success"}

on failure, response will be

{
  "status":"fail", 
  "error":{ 
    "type": "TypeError",
    "message":"expected string"
  }
}

The following status codes and associated error messages will be returned if your request encounters 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

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 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 authentication header

App_key is not present in authentication header

401

Authentication required

APP_SECRET missing in authentication header

App_secret os not present in authentication header

401

Authentication required

App Secret key mismatch. Please login to 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 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 params and auth do not match

409

Authentication required

App Secret key is not set. Please login to dashboard to set a key

App Secret not set

413

Payload too large

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 (no. of users / events per minute) defined for your MoEngage account.

500

Server Error

Any other exception

API Limits

The MoEngage Data Import API is designed to handle high volumes of data across our customer base. We enforce API limits to ensure responsible use of the API.

Recommended rate limits of the Data Import APIs are as below -

API Name
Rate Limit
Description

User

1,000 users / min

A single API request can contain one or more than one user updates. You should maintain a rate limit of 1000 user updates per minute.

Event

10,000 events/min

A single API request can contain one or more than one events. You should 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 can contain users, devices and events together. You should only send maximum 1000 users and 10000 events per min across all your API requests

Please note that on breaching the rate limits, your requests will be rejected with a response code of 429.

If you need higher limits or have any questions on the API limits, please contact your Customer Success Manager or send an email to our Support Team at support@moengage.com.

Add/Modify User Information

API to use - User API
This API allows you to create a new user profile (or) update profile data of existing user. It includes customer_id (Unique Identifier of User) and other User Attributes(ex: name, age etc.. ). customer_id will be used to Map Actions and Devices to User.

NOTE: customer_id is essentially the Unique Identifier which is set and passed on from MoEngage SDK as USER_ATTRIBUTE_UNIQUE_ID

customer_id in customer payload is mandatory to identify a user profile.

Signature for a user API request looks like:

POST https://api.moengage.com/v1/customer/<APP ID>

To set name as John for a user with unique id john@example.com and platform android, pass the following payload

{
"type" : "customer",
"customer_id": "john@example.com",
"attributes": {
    "name":"John",
    "platforms" : [{"platform":"ANDROID", "active":"true"}]
    }
}

User attributes list is mentioned below:

  • name (string) - name of the user
  • first_name (string) - first name of the user
  • last_name (string) - last name of the user
  • email (string) - email of the user
  • age (numeric) - age of the user
  • gender (string) - "male" or "female" - case sensitive
  • mobile (string) - phone number of the user
  • geo (array of lat,lng in double) - location of the user for eg. [23.3,37.3]
  • source (string) - acquisition source of the user
  • created_time (numeric - epoch time in seconds) - user created time
  • last_seen (numeric - epoch time in seconds) - user last seen time
  • transactions (numeric) - no.of transactions done by the user
  • revenue (numeric) - LTV of the user
  • platforms (array) - platforms on which the user has interacted with the system. for eg.[{"platform":"ANDROID", "active":"true"},{"platform":"WINDOWS", "active":"true"},{"platform":"IOS", "active":"true"}]

To pass other attributes which are not part of the list, use the key value pairs that you intend to use. for ex. to set the points attribute for the user to 20

{
"type" : "customer",
"customer_id": "john@example.com",
"attributes": {
    "points":20,
    "platforms" : [{"platform":"ANDROID", "active":"true"}]
    }
}

The following keywords are blocked and should not be used as attribute names - "id", "_id", ""

Mandatory fields: customer_id.

Add/Modify Device Information

API to use - Device API
This API allows you to create a new device profile (or) update profile data of existing device. It includes customer_id (Identifier of User), device_id (Identifier of Device) and other Device Attributes(ex: model, brand, os version etc.. ).

NOTE: customer_id is essentially the Unique Identifier which is set and passed on from MoEngage SDK as USER_ATTRIBUTE_UNIQUE_ID

customer_id in device payload is mandatory to map device to user.
platform in device attributes is mandatory to run platform level campaigns.
device_id in device payload is optional and default value is customer_id value. It will be used to update specific device in future.

Signature for a device API request looks like:

POST https://api.moengage.com/v1/device/<APP ID>
{
  "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
  }
}

We defined reserved keywords for some of Device Attributes.

"model"  (string):  Model of Device
"platform" (string): os (ex: iOS)
"push_preference"  (string): is Push Enabled for Device ("true" or "false") 
"push_id" (string): Push Id or Push Token of Device. 
"app_version" : App Version
"os_version" : Os Version
"active" :   Installed status of device ("true" or "false")     
"created_time" : Created Time of Device (Epoch time in seconds)

To pass other attributes which aren't part of the list, use the key value pairs that you intend to use. for ex. to set the brand attribute for the device to Apple

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

The following keywords are blocked and should not be used as attribute names - "id", "_id", ""
Mandatory fields: customer_id, platform and push_id.

User Events Information

API to use - Event API
This API allows you to track actions of a user.

customer_id in event payload is mandatory to map event to user.
device_id in event payload is optional and default value is customer_id value. It will be used to map event to specific device.
platform in event payload is Not Mandatory If you do not pass platform in the event payload, we will set it as unknown on our side automatically.
Please note that you can send the platform value as Android, iOS or web based on the platform on which this event was generated.
If you are unsure about the platform on which this event happened, please send the value as unknown or do not send the value at all. Incorrect platform value will lead to inconsistencies in platform level campaigns.

Signature for event API request looks like:

POST https://api.moengage.com/v1/event/<APP ID>
{
	"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_time_zone_offset": 19800
		},
		{
			"action": "Purchase",
			"attributes": {
				"product": "MacBook Air",
				"Brand": "Apple"
			},
			"platform": "web",
			"app_version": "1.2.3",
			"current_time": 1433837969,
			"user_time_zone_offset": 19800
		}
	]
}

Please note that we were accepting current_time and user_time earlier and the difference between user_time and current_time was used to calculate the timezone in which the even happened.

Currently, we are supporting 3 combinations - user_time and user_time_zone_offset, current_time and user_time_zone_offset and user_time and current_time to calculate the timezone of the event.

user_time_zone_offset should have a value in seconds which can be between -54000 to 54000. For example, for IST (UTC+0530), "user_time_zone_offset" will be 19800

We defined reserved keywords for Event Name and Event Attributes.

"actions" (array) : Array of Actions or events
"action"  (string): Name of Action or Event
"attributes" (json object) - Event Attributes
"platform" (string) - os 
"app_version" (string or numeric) - App Version
"user_time" (Epoch Time in seconds) - User Time
"current_time" (Epoch Time in seconds) - GMT time of User Time
"user_time_zone_offset" (integer in seconds) - offset to determine the timezone in which the event was performed

The following keywords are blocked and should not be used as event attribute names - "id", "_id", ""

Mandatory fields: customer_id and action.

Bulk Import

API to use - Transition API
This API allows you to import “user , device and event requests” in a single batch.

Signature for transition API request looks like:

POST https://api.moengage.com/v1/transition/<APP ID>
{
	"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": 1433837969,
					"user_time_zone_offset": 19800
				},
				{
					"action": "Purchase",
					"attributes": {
						"product": "MacBook Air",
						"Brand": "Apple"
					},
					"platform": "iOS",
					"app_version": "1.2.3",
					"current_time": 1433837969,
					"user_time_zone_offset": 19800
				}
			]
		}
	]
}

Data APIs


Data APIs are used to send user data (user properties and events) from your servers to MoEngage.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.