Overview

Data API helps in sending events and user details from your servers to MoEngage servers.

Data API is a collection of the following APIs

Request Headers

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

Navigate to Settings > APIs > DATA API Settings
Click Generate Key
Save the details on the Data APIs settings page. User name - DATA API ID Password - DATA API KEY

warning

Warning

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:

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.

info

Note

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:

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:

{"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 is 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.
5xx	Server Error	Any other exception	This response is returned when the system runs into an unexpected error. We recommend that you retry every 2 seconds for a maximum of 5 times in such cases.

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	5,000 users per min	A single API request contains one or more user updates. Maintain a rate limit of 5,000 user updates per minute.
Event	20,000 events/min	A single API request contains one or more than one event. Maintain a rate limit of 20,000 events per minute.
Bulk Import	5,000 users/min and 20,000 events/min	A single bulk import API contains users, devices, and events together. Send a maximum of 5000 users and 20000 events per minute across all API requests.

info	Note The values mentioned above are default limits. If your requirement exceeds these limits, you can get in touch with the MoEngage support team to increase the limits.