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:

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

Was this article helpful?
2 out of 3 found this helpful

How can we improve this article?