MoEngage Docs

Data APIs

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

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.

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.

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.

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 than one 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 events. 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.

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

Key

Datatype

Mandatory Field

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

A 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.

Standard User Attributes

The following standard user attributes are tracked for User API 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 example: [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 Example: 918888444411

moe_geo_location

Location

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

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

source

Publisher Name

String

This is the Publisher Name of Install. . For example: Google Ads

created_time

First Seen

Date

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

last_seen

Last Seen

Date

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

transactions

Number of Conversions

Numeric

Total number of conversions made by the user in a lifetime.

revenue

LTV

Numeric

Life Time Value of the user.

moe_unsubscribe

Unsubscribe

Boolean

Email Unsubscribe Attribute.
Emails are not sent to the user when set value is true.

platforms

Not visible on dashboard.

List

Value are based on the active platforms of the user.
For example: [{"platform":"ANDROID", "active":"true"},{"platform":"IOS", "active":"true"}]

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

Key

Datatype

Mandatory Field

Description

type

String

Yes

Identify the request type.

customer_id

String

Yes

Identifier to identify or create a user in MoEngage.

device_id

String

No

Identify specific devices in MoEngage. If this field is not present, MoEngage will create a new device.

attributes

JSON Object

No

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

platform

String

Yes

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

push_id

String

Yes

Push Id or Push Token used to send a push notification to the device.

Standard User Attributes

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

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

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

Key

Datatype

Required

Description

type

String

Yes

Identify the type of request.

customer_id

String

Yes

Identifier to identify or create a user in MoEngage.

device_id

String

No

device_id in event payload is optional. Default value is customer_id value. The value is 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 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

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

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

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.

Updated about a month 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.