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

Data API Endpoints

MoEngage supports multiple data centers with different dashboards and data API endpoints. When you sign up with MoEngage, you will be assigned a particular data center and the relevant dashboard is displayed. Use the data API endpoints associated with the data center.

For more information about your data center, contact support@moengage.com.

You can find out which data center you are assigned to when you log in to the dashboard. The following table describes the dashboard URL and data API endpoint associated with the data center.

Two versions of the dashboard URL and data API endpoints are provided by MoEngage.

Data Centers and API Endpoints

Data Center Name Dashboard URL Data API Endpoint
Data Center 1(DC-01) http://dashboard-01.moengage.com/ https://api-01.moengage.com/v1/
Data Center 2(DC-02) http://dashboard-02.moengage.com/ https://api-02.moengage.com/v1/
Data Center 3(DC-03) http://dashboard-03.moengage.com/ https://api-03.moengage.com/v1/

For more information about MoEngage data centers, refer to Data Centers in MoEngage

Syntax

Text
POST https://api-01.moengage.com/v1/
POST https://api-02.moengage.com/v1/
POST https://api-03.moengage.com/v1/

Request Headers

Request headers are applicable to User, Device, Event, and Bulk Import APIs.

Authentication

Basic authentication sends a Base64-encoded string containing username and password for all API requests. Authentication is applicable to User, Device, Event, and Bulk Import APIs.Username and password are available at Settings > APIs > DATA API SettingsDo the following when you are using the API for the first-time authentication:

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.
  1. Navigate to Settings > APIs > DATA API Settings
  2. Click Generate Key
  3. Save the details on the Data APIs settings page. User name - DATA API ID Password - DATA API KEY
  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.

 

Allowed values of customer_id

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 os 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.
500 Server Error Any other exception

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 1,000 users per min A single API request contains one or more user updates. Maintain a rate limit of 1000 user updates per minute.
Event 10,000 events/min A single API request contains one or more than one event. Maintain a rate limit of 10,000 events per minute.
Bulk Import 1,000 users/min and 10,000 events/min A single bulk import API contains users, devices, and events together. Send maximum of 1000 users and 10000 events per minute across all API requests.
 

API Limits Breaching

Please note that on breaching the rate limits, your requests will be rejected with a response code of 429.

Import APIs for Postman

 

 

Was this article helpful?
0 out of 0 found this helpful