Data APIs will enable you to send events and users to MoEngage from your servers. To use Data APIs, identify the MoEngage Data Center that you have signed up with.

MoEngage Data Centers

As of now, MoEngage supports 3 data centers and depending on your requirement to save your user's data in specific geographical regions, you could sign-up with either one of the below data centers while beginning to use MoEngage. Each data center will also have a different moengage dashboard URL and API endpoint. The mapping for the same is as below -

To be able to identify your data center, login to moengage and look at the dashboard URL that you are using.

📘

Note:

By default, MoEngage will always sign you up on our Default Data Center even if you are based in Europe, Asia or any other region.

List of APIs

Depending on the data center you signed-up with, below are the APIs that you need to use -

APIs for Default Data Center

📘

MoEngage APP ID

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

APIs for EU Data Center

Please note that we no longer need the app_id to be passed as a parameter in the APIs for EU Data Center APIs. This was required earlier. The APIs will not break irrespective of whether app_id is present as a parameter or not.

📘

APP ID

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

APIs for India Data Center

📘

APP ID

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

Headers, Authentication, Limits, Response Codes

Required Headers

Authentication

Data APIs use Basic authentication to control access to your data.

Basic authentication sends a Base64-encoded string that contains a username and password for your API requests. username and password are available under following path: (Settings > APIs > DATA API Settings) as shown below.

For first time, hit the Generate Key and then save on Data APIs settings page.
User name - DATA API ID
Password - DATA API KEY

Basic Authentication encodes a 'username:password' using base64 and prepends it with the string 'Basic '. This is passed in the authorization header as follows
{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

To send a request using a client (as Postman), Authentication can be done in following way:

Request Body

There is a max limit of 100kb per request.

Sample Response

Response will be a json object, on a sucessful call you will receive response as

{"status":"success"}

on failure, response will be

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

The following status codes and associated error messages will be returned if your request encounters a fatal error.

Response Codes

Limits

The MoEngage Data Import API is designed to handle high volumes of data across our customer base. We enforce API limits to ensure responsible use of the API.

Recommended rate limits of the Data Import APIs are as below -

🚧

API Limits Breaching

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

If you need higher limits or have any questions on the API limits, please contact your Customer Success Manager or send an email to our Support Team at [email protected]

User API

User API allows you to add/update users and user properties in MoEngage. You can create a new user, a new user property or update updating existing user properties of users. It includes customer_id (Unique Identifier of User) and other User Attributes(ex: name, age etc.. ).

API Endpoint:

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

A sample request body to set name as John for a user with unique id [email protected] and active platform as android, is as below -

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

Request Body Fields -

Below are the standard user attributes that can be tracked in MoEngage -

To pass other attributes which 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 is 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 user attribute name

The following keywords are blocked and should not be used as user attribute names - "id", "_id", ""

Once an attribute is tracked in the required datatype, you would be able to see different filters while creating campaigns and segments. For example, when an attribute is tracked in numeric datatype, you would see the below filters -

When an attribute is tracked as a string, you would see the below filters -

When an attribute is tracked as a date attribute, you would see the below filters -

For example, when an attribute is tracked as a boolean attribute, you would see the below filters -

Device API

Device API allows you to create a new device profile (or) update profile data of existing device. It includes customer_id (Identifier of User), device_id (Identifier of Device) and other Device Attributes(ex: model, brand, os version etc.. ).

API Endpoint:

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

A sample API request body looks like below -

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

JSON fields of the request body

Below are the standard device attributes that MoEngage supports -

📘

Using Device Attributes in MoEngage

Please note that device attributes are only visible in MoEngage Analytics module right now and not visible on the dashboard for Segmentation, Campaigns and User Profile.

To pass other attributes which aren't part of the list, use the key value pairs that you intend to use. for ex. 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

The following keywords are blocked and should not be used as device attribute names - "id", "_id", ""

📘

Regarding updating existing devices in moengage

For devices created by moengage SDK, device_id is internal and is not available for use externally as of now.

You would not be able to update the device profiles created by moengage SDK. You can only create new device profiles and map it to the appropriate user profile by providing the correct customer_id or update the device profiles created by you by using the appropriate device_ids in the request.

Event API

Event API allows you to track actions of a user.

API Endpoints:

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

A sample API request looks like this -

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

JSON body fields

🚧

Platform

Please note that you can send the platform value as Android, iOS or web based on the platform on which this event was generated.
If you are unsure about the platform on which this event happened, please send the value as unknown or do not send the value at all. Incorrect platform value will lead to inconsistencies in platform level campaigns like Push and In-App.

📘

Time of the event

MoEngage relies on current_time and user_timezone_offset for figuring out the local time at which the event happened and this local time is shown in the user profile on the dashboard.

User_timezone_offset is used to determine the local timezone in which the event happened. If not present, moengage will use the timezone present in user profile else will consider that the event happened in UTC

current_time is used to identify the UTC time at which the event happened. If not present, moengage will use the time at which the request was received 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 while user_timezone_offset should have a numeric value between -54000 to 54000 which will be the timezone offset of the local time from UTC in seconds.

To track numeric, boolean and date type event attributes, pass the following payload where price is a number, 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, you would able to see different filters corresponding to the data type of the event attributes like below -

📘

Reserved keywords for event and event attribute names

The following keywords are blocked and should not be used as event attribute names - "id", "_id", "userId", "".

Bulk Import

This API allows you to batch multiple “user , device and event requests” in a single API request and send to MoEngage. You can batch requests of maximum 100 kB in a single API call.

API endpoint -

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

A sample API request is as below -

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

JSON Fields

📘

API Validation for Bulk API

We currently return a 200 response for all bulk API requests so debugging should be done on the user profile on the dashboard.

Importance of customer_id

In all Data APIs, customer_id is a mandatory field in the request body as this is used to identify / create a user in moengage and also map the events to the corresponding unique user profiles in moengage. When a data API request is received by moengage, we first try to identify if the user with same customer_id already exists in MoEngage and if not, we will create a new user and add the attributes / events in the newly created user.

🚧

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']

customer_id is essentially the Unique Identifier which is set and passed on from MoEngage SDK as USER_ATTRIBUTE_UNIQUE_ID and is visible on the dashboard as ID. For example a user which is created by the following request will be visible in the dashboard user profile as follows -

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

Import APIs in to Postman

We have made it easy for you to test the apis, If you are using Postman, click on the following button to export our Data APIs in to your Postman collections.