MoEngage Docs

Data APIs

Data APIs are used to send user data (user properties and events) from your servers to MoEngage.

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

API Name

Details

Endpoint

User

Use this API to send user properties.

POST https://api.moengage.com/v1/customer/

Event

Use this API to send events.

POST https://api.moengage.com/v1/event/

Device

Use this API to send device properties.

POST https://api.moengage.com/v1/device/

Bulk Import

User this API to import data in bulk.

POST https://api.moengage.com/v1/transition/

πŸ“˜

MoEngage APP ID

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

APIs for EU Data Center

API Name

Details

Endpoint

User

Use this API to send user properties.

POST https://api-eu.moengage.com/v1/customer/

Event

Use this API to send events.

POST https://api-eu.moengage.com/v1/event/

Device

Use this API to send device properties.

POST https://api-eu.moengage.com/v1/device/

Bulk Import

User this API to import data in bulk.

POST https://api-eu.moengage.com/v1/transition/

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

API Name

User

Use this API to send user properties.

POST https://api-serv3.moengage.com/v1/customer/

Event

Use this API to send events.

POST https://api-serv3.moengage.com/v1/event/

Device

Use this API to send device properties.

POST https://api-serv3.moengage.com/v1/device/

Bulk Import

User this API to import data in bulk.

POST https://api-serv3.moengage.com/v1/transition/

πŸ“˜

APP ID

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



Headers, Authentication, Limits, Response Codes


Required Headers

Header

Sample Value

Description

Authorization

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U="}

Data APIs use Basic authentication for access control. Refer this section for more information.

Content-Type

{"Content-Type": "application/json"}

While using Data APIs, Content-Type header must be set to 'application/json'.

MOE-APPKEY

{"MOE-APPKEY": "APP ID"}

While using Data APIs, MOE-APPKEY header must be set to which is available here: (Settings > App Settings > Account Settings > APP ID)


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

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

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 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 authentication header

App_key is not present in authentication header

401

Authentication required

APP_SECRET missing in authentication header

App_secret os not present in authentication header

401

Authentication required

App Secret key mismatch. Please login to 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 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 params and auth do not match

409

Authentication required

App Secret key is not set. Please login to dashboard to set a key

App Secret not set

413

Payload too large

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 (no. of users / events per minute) defined for your MoEngage account.

500

Server Error

Any other exception


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 Name

Rate Limit

Description

User

1,000 users / min

A single API request can contain one or more than one user updates. You should maintain a rate limit of 1000 user updates per minute.

Event

10,000 events/min

A single API request can contain one or more than one events. You should 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 can contain users, devices and events together. You should only send maximum 1000 users and 10000 events per min across all your API requests

🚧

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 -

Key

Datatype

Required

Description

type

String

Yes

This is used to identify the type of request.

customer_id

String

Yes

The unique identifier used to identify / create a user in moengage. Please refer this section for more information on customer_id.

attributes

JSON Object

No

Dictionary containing user attributes to add / update in the user profile.

platforms

List

No

List of dictionaries with the associated platforms out of ANDROID, iOS and web and their status.

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

Key

Attribute Name on Dashboard

Datatype

Description

name

Name

String

Full name of the user.

first_name

First Name

String

First name of the user

last_name

Last Name

String

Last name of the user

email

Email

String

Email Address of the user for ex. [email protected]

age

Age

Numeric

Age of the user

gender

Gender

String

Gender of the user

mobile

Mobile Number

String

Mobile Number of the user for ex 918888444411

moe_geo_location

Location

Array of [lat,lng] in double in this format - {'lat': 12.11, 'lon': 123.122}

A sample value would be the location of the user for ex. {'lat': 12.11, 'lon': 123.122}

source

Publisher Name

String

This is the Publisher Name of Install for ex. Google Ads

created_time

First Seen

Date

Time when the user was created. Pass this in ISO 8601 format. For ex. 2019-05-21T03:47:35Z

last_seen

Last Seen

Date

Last Seen Time of the user. Pass this in ISO 8601 format. For ex. 2020-05-01T03:52:35Z

transactions

No. of Conversions

Numeric

Total number of conversions made by the user in lifetime.

revenue

LTV

Numeric

Life Time Value of the user.

moe_unsubscribe

Unsubscribe

Boolean

Email Unsubscribe Attribute. Emails will not be sent to the user when this is set as true.

platforms

This is not visible on dashboard.

List

Value should be basis the active platforms of the user -[{"platform":"ANDROID", "active":"true"},{"platform":"IOS", "active":"true"}]

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

Key

Datatype

Required

Description

type

String

Yes

This is used to identify the type of request.

customer_id

String

Yes

Identifier to identify / create a user in moengage. Please refer this section for more information on customer_id.

device_id

String

No

This is used to identify specific devices in MoEngage. If this is not present, MoEngage will create a new device.

attributes

JSON Object

No

Dictionary containing device attributes to add / update in the device profile.

platform

String

Yes

Platform is the type of device and is required to run push and in-app campaigns.. Allowed values are ANDROID, iOS or web

push_id

String

Yes

Push Id or Push Token which is used to send a push notification to this device

Below are the standard device attributes that MoEngage supports -

Key

Datatype

Description

model

String

Model of Device

push_preference

Boolean

If push notifications are enabled for this device

app_version

String

App version of the app currently present on this device.

os_version

String

OS version of the device

active

Boolean

If the app is currently active (installed) on this device or not.

created_time

Numeric (Epoch time in seconds)

Time when this device was created.

πŸ“˜

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

Key

Datatype

Required

Description

type

String

Yes

This is used to identify the type of request.

customer_id

String

Yes

Identifier to identify / create a user in moengage. Please refer this section for more information on customer_id.

device_id

String

No

device_id in event payload is optional and default value is customer_id value. It will be used to map event to specific devices.

actions

List

Yes

List of events to be tracked for the user.

action

String

Yes

The name of the event to be tracked.

attributes

JSON Object

No

Dictionary containing event attributes to track along with the event.

platform

String

No

Used to identify the platform on which the event happened. Allowed values are ANDROID, iOS, web or unknown.

app_version

String

No

App Version of the app on which the event originated.

user_time

Numeric(Epoch time in seconds) or String (ISO 8601 - )

No

Local Time at which the event happened.

current_time

Numeric (Epoch time in seconds) or String( ISO 8601)

No

UTC Time at which the event happened

user_timezone_offset

Numeric

No

user_timezone_offset should have a value in seconds which can be between -54000 to 54000. For example, for IST (UTC+0530), "user_timezone_offset" will be 19800

🚧

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

Key

Datatype

Required

Description

type

String

Yes

This is used to identify the type of request.

element

List

Yes

List of data points (events, customers and devices) to track.

πŸ“˜

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.

Updated 12 days ago

Data APIs


Data APIs are used to send user data (user properties and events) from your servers to MoEngage.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.