Data API helps in sending events and user details from your servers to the 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 ID by default 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 activated in the Identity Resolution dashboard.

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 performed using a client like Postman as follows:

Request Body

The request body contains the mandatory field called customer_id. customer_id is the unique identifier set and passed on from the 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.

Sample Request Body 

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

Supported Datetime Formats

You can pass the datetime in the following formats in the request body:

Response

Response to the Data API is a JSON object. On a successful data API request, you will receive the following response:

{
"status":"success",
"message": "Your request has been accepted and will be processed soon."
"request_id": "kXwpDESb"
}

On a failed data API request, you will receive the following response:

{
  "status":"fail", 
  "error":{ 
    "type": "TypeError",
    "message":"expected string"
    "request_id": "kXwpDESb
  }
}

Response Codes

The following status codes and associated error messages are returned when the request results in a fatal error.

Rate Limit Headers

When you make a request to the Data APIs, MoEngage returns specific rate-limiting information within the Response Headers. These headers allow you to programmatically monitor your API usage and prevent hitting your workspace limits.

You can track your usage using the following three headers:

Example Scenario
Based on a typical API response, here is how to interpret these values in real-time:

• x-ratelimit-limit: 31500; w=60
  This means your workspace is permitted to make 31,500 events every 60 seconds (w=60).
• x-ratelimit-remaining: 31499
  This means you have successfully made a request with 1 event in the current window, leaving you with 31,499 events available before you are throttled.
• x-ratelimit-reset: 29
  This means you have exactly 29 seconds left until the current time window ends. Once this hits 0, your x-ratelimit-remaining will automatically reset back to 31,500.

User Attributes

Dashboard User Profile

On sending data through the data API, it will be populated in the user profile as shown below:

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: