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

The API request will be authenticated through Basic Authentication. 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 bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

  1. Navigate to Settings -> Account -> APIs.
  2. Click Generate Key in the Data tile in the API Keys section, and click Save.
  3. Use the App ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

  1. Navigate to Settings -> APIs -> DATA API Settings.
  2. Click Generate Key.
  3. Click Save on the Data APIs settings section. 
  4. Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.
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.
Revamped Settings Old Settings
API_Authentication_RevampedUI.png

Authentication is applicable to Create User, Create Event, and Bulk Import APIs. 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.

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 Create 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"}]
    }
}

 

info

Note

You can not use "moe_" as a prefix while naming events, event attributes, or user attributes. It is a system prefix and using it might result in periodic blacklisting without prior communication.

 

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

Previous

Next

Was this article helpful?
6 out of 14 found this helpful

How can we improve this article?