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
• Track Device API
• Create Event API
• Bulk Import API
• Trigger File Imports API

In MoEngage, data ingestion uses an ID to create or update a user. For workspaces in MoEngage with Identity Resolution enabled, Data APIs (Track User, Create Event, Bulk Import) can be used to create or update users using a specific identifier, such as a mobile number or email ID, as configured.

You can:

• Create users through Server-to-Server Data APIs even when they do not have an ID (but have other identifiers).
• Create a user or track events of a user when identifiers other than ID (for example, email ID or phone number) are known.

Request Headers

Authentication

You can obtain the username and password details from the MoEngage Dashboard.

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 Base64_ENCODED_WORKSPACEID_APIKEY=="}

The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps:

1. Navigate to Settings -> Account -> APIs.
2. Copy the following details:
   • Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
   • Password: In the API keys section, click the copy icon in the Data tile to copy the API key.
3. Use these details to authenticate the API requests.

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: