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

Data API is a collection of the following APIs

• User API
• Device API
• Event API
• Bulk Import API

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 [email protected]

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

Please note that we will continue to support both the old and new data API endpoints mentioned in the above table for foreseeable future but we recommend out customers to move to the new endpoints as soon as possible.

Syntax

New version

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

Old version

POST https://api.moengage.com/v1/
POST https://api-eu.moengage.com/v1/
POST https://api-serv3.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 Settings

Do the following when you are using the API for the first-time authentication:

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

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.

📘

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

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

📘

API Limits Breaching

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

User API

User API helps add or update users and user properties in MoEngage. You can do the following:

• Create a new user
• Create new user property
• Update existing user properties of users

EndPoints

Syntax

New Version for different data centers

POST https://api-01.moengage.com/v1/customer/<APP ID>
POST https://api-02.moengage.com/v1/customer/<APP ID>
POST https://api-03.moengage.com/v1/customer/<APP ID>

Older Version for different data centers

POST https://api.moengage.com/v1/customer/<APP ID>
POST https://api-eu.moengage.com/v1/customer/<APP ID>
POST https://api-serv3.moengage.com/v1/customer/<APP ID>

👍

Support for Old and New Endpoints

Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.

📘

APP_ID

The APP_ID for your moengage account is available here: (Settings > App Settings > Account Settings > APP ID).

Request Body

A sample request body is described for user with unique id [email protected], where the following is set:

Name

John

Active Platform

Android

{
"type" : "customer",
"customer_id": "[email protected]",
"attributes": {
    "name":"John",
    "platforms" : [{"platform":"ANDROID", "active":"true"}]
    }
}

Request Body Fields

Standard User Attributes

The following standard user attributes are tracked for User API in MoEngage.

For other attributes that are not part of the list, use the key-value pairs that you intend to use.

For example, to track custom attributes of different data types like string, numeric, boolean, and date, pass the following payload where points are a number, expiry_date is a date type attribute and super_user is a boolean attribute.

{
"type" : "customer",
"customer_id": "[email protected]",
"attributes": {
    "points":20,
    "expiry_date":"2020-05-31T03:47:35Z",
    "super_user":true,
        "user_persona":"browsers",
    "platforms" : [{"platform":"ANDROID", "active":"true"}]
    }
}

📘

Reserved keywords for the user attribute name

"id", "_id", and "" keywords are blocked and do not use as user attribute names.

Different filters are available during the creation of campaigns and segments after an attribute is tracked in the required data type.

Examples

When an attribute is tracked in numeric data type, the following filters are displayed:

When an attribute is tracked as a string, the following filters are displayed:

When an attribute is tracked as a date attribute, the following filters are displayed:

For example, when an attribute is tracked as a boolean attribute, the following filters are displayed:

Device API

Device API helps to

• Create a new device profile
• Update profile data of an existing device.

Device API attributes include customer_id (Identifier of User), device_id (Identifier of Device), and other Device Attributes such as model, brand, os version, and so on.

Endpoints

Syntax

New Version for different data centers

POST https://api-01.moengage.com/v1/device/<APP ID>
POST https://api-02.moengage.com/v1/device/<APP ID>
POST https://api-03.moengage.com/v1/device/<APP ID>

Older version for different data centers

POST https://api.moengage.com/v1/device/<APP ID>
POST https://api-eu.moengage.com/v1/device/<APP ID>
POST https://api-serv3.moengage.com/v1/device/<APP ID>

👍

Support for Old and New Endpoints

Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.

Request Body

A sample API request body is as follows:

{
  "type": "device",
  "customer_id": "[email protected]",
  "device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
  "attributes": {
    "model": "iPhone",
    "platform" : "iOS",
    "push_preference" : "true",
    "push_id" : "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I",
    "app_version" : "10.1",
    "os_version" : "2.5.4",
    "active" : "true",
    "created_time" : 143383676
  }
}

Updating existing devices in MoEngage

For devices created by MoEngage SDK, device_id is internal and is not available for use externally.

You cannot update the device profiles created by MoEngage SDK. You can only create new device profiles and associate them to the appropriate user profile by

• Providing the correct customer_id
• Update the device profiles created by you by using the appropriate device_ids in the request.

Request Body Fields

Standard User Attributes

The following standard user attributes are tracked for Device API in MoEngage.

📘

Using Device Attributes in MoEngage

Device attributes are only visible in the MoEngage Analytics module and not visible on the dashboard for Segmentation, Campaigns and User Profile.

For other attributes not part of the list, use the key-value pairs that you intend to use. For example, to set the brand attribute for the device to Apple

{
  "type": "device",
  "customer_id": "[email protected]",
  "device_id" : "96bd03b6-defc-4203-83d3-dc1c73080232",
  "attributes": {
    "brand": "Apple",
    "platform": "iOS",
    "push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
  }
}

🚧

Reserved Keywords for Device Attribute names

"id", "_id", "" keywords are blocked and do not use in device attribute names.

Event API

Event API allows you to track the actions of a user.

Endpoints

Syntax

New Version for different data centers

POST https://api-01.moengage.com/v1/event/<APP ID>
POST https://api-02.moengage.com/v1/event/<APP ID>
POST https://api-03.moengage.com/v1/event/<APP ID>

Older Version for different data centers

POST https://api.moengage.com/v1/event/<APP ID>
POST https://api-eu.moengage.com/v1/event/<APP ID>
POST https://api-serv3.moengage.com/v1/event/<APP ID>

👍

Support for Old and New Endpoints

Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.

Request Body

A sample API request is described:

{
    "type": "event",
    "customer_id": "[email protected]",
    "device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
    "actions": [{
            "action": "Added to Cart",
            "attributes": {
                "product": "Mobile",
                "color": "white",
                "Brand": "Apple"
            },
            "platform": "iOS",
            "app_version": "1.2.3",
            "current_time": 1433837969,
            "user_timezone_offset": 19800
        },
        {
            "action": "Purchase",
            "attributes": {
                "product": "MacBook Air",
                "Brand": "Apple"
            },
            "platform": "web",
            "app_version": "1.2.3",
            "current_time": 1433837969,
            "user_timezone_offset": 19800
        }
    ]
}

Request Body Fields

🚧

Platform

Ensure that the platform value sent is Android, iOS or web. Platform value depends on the which platform the event was generated.
If you are unsure about the platform on which the event occured, send the value as unknown or do not send any value. Incorrect platform value leads to inconsistencies in platform level campaigns like Push and In-App.

📘

Time of the event

MoEngage depends on current_time and user_timezone_offset for generating the local time at which the event occurred. The local time is displayed in the user profile on the dashboard.

user_timezone_offset

Used to determine the local timezone at which the event occurred.

If the field is not present, then either one of the following is used: *The timezone present in user profile is considered. *The event occurred in UTC timezone.

Format contains numeric value between -54000 to 54000. The value is the timezone offset of the local time from UTC in seconds.

current_time

Used to identify the UTC time at which the event occurred.

If the field is not present, then the time at which the request was received is used as the current_time.

Allowed formats for current_time are ISO 8601 , for example 2020-05-31T16:33:35Z or Epoch time in seconds, for example - 1590404615

Examples

The following example provides tracking of numeric, boolean, and date type event attributes.
Use the payload described, where the price is numeric, departure_date is a date type attribute and premium_seat is a boolean attribute.

{
    "type": "event",
    "customer_id": "[email protected]",
    "actions": [{
            "action": "Flight Bookoed",
            "attributes": {
                "price": 3999,
                "departure_date": "2019-05-21T03:47:35Z",
                "premium_seat": true
            },
            "platform": "iOS",
            "app_version": "1.2.3",
            "current_time": 1433837969,
            "user_timezone_offset": 19800
        }
    ]
}

Different attribute types allow you to use the relevant filters while creating segments. For example, when you track the above event, different filters corresponding to the data type of the event attributes are displayed as follows:

📘

Reserved keywords for event and event attribute names

"id", "_id", "userId", "" keywords are blocked and do not use in event attribute names.

Bulk Import

Use the Bulk Import API to send, to MoEngage, in batch multiple user, device, and event requests using a single API request. You can send a batch request of a maximum of 100 kB in a single API call.

Endpoints

Syntax

New version for different data centers

POST https://api-01.moengage.com/v1/transition/<APP ID>
POST https://api-02.moengage.com/v1/transition/<APP ID>
POST https://api-03.moengage.com/v1/transition/<APP ID>

Older version for different data centers

POST https://api.moengage.com/v1/transition/<APP ID>
POST https://api-eu.moengage.com/v1/transition/<APP ID>
POST https://api-serv3.moengage.com/v1/transition/<APP ID>

👍

Support for Old and New Endpoints

Support for both old and new data API endpoints will be available, but we recommend that you start using the new endpoints as soon as possible.

Request Body

A sample API request is as follows:

{
    "type": "transition",
    "elements": [{
            "type": "customer",
            "customer_id": "[email protected]",
            "attributes": {
                "name": "John",
                "platforms": [{
                    "platform": "ANDROID",
                    "active": "true"
                }]
            }
        },
        {
            "type": "device",
            "customer_id": "[email protected]",
            "device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
            "attributes": {
                "brand": "Apple",
                "platform": "iOS",
                "push_id": "irBMohQPf_k2QrwP8iRzK3A/0CdLEzAoVGdF65HhH_I"
            }
        },
        {
            "type": "event",
            "customer_id": "[email protected]",
            "device_id": "96bd03b6-defc-4203-83d3-dc1c73080232",
            "actions": [{
                    "action": "Added to Cart",
                    "attributes": {
                        "product": "Mobile",
                        "color": "white",
                        "Brand": "Apple"
                    },
                    "platform": "iOS",
                    "app_version": "1.2.3",
                    "current_time": "2020-05-31T16:33:35Z",
                    "user_timezone_offset": 19800
                },
                {
                    "action": "Purchase",
                    "attributes": {
                        "product": "MacBook Air",
                        "Brand": "Apple"
                    },
                    "platform": "iOS",
                    "app_version": "1.2.3",
                    "current_time": 1590404615,
                    "user_timezone_offset": 19800
                }
            ]
        }
    ]
}

Request Body Fields

📘

API Validation for Bulk API

All bulk API requests return a 200 response code. Debugging should be done on the user profile on the dashboard.

Import APIs for Postman

We have made it easy for you to test the APIs.
Click on the following button to export our Data APIs into your Postman collections.