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

Data API is a collection of the following APIs

• Track User API
• Get User API
• Merge User API
• Delete User API
• Create Event API
• Bulk Import API
• Trigger File Imports API

Request Headers

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 user interface in the Dashboard. If you're using the API for the first time, follow the steps below for the revamped and old user interfaces:

Revamped UI

1. Navigate to Settings > Account > APIs > Workspace ID.
2. Click Generate Key in the Data tile in the API Keys section to generate a key and then click Save.
3. Use the Workspace 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.

Revamped Settings Old Settings

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

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

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

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.

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: