Track User

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

API Endpoint


The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. You can find your DC number (value of X) and replace the value of 'X' in the URL by referring to the DC and API endpoint mapping here.



The APP_ID for your MoEngage account is available on the MoEngage Dashboard. We've revamped our settings UI; you can find the APP_ID in the following navigations in the revamped and old UIs:

    • Revamped UI: Settings -> Account -> APIs -> App ID
    • Old UI: Settings -> App Settings -> Account Settings -> APP ID

Request Body

A sample request body is described for the user with the unique id

"type": "customer",
"customer_id": "",
"attributes": {
    "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. 

Allowed Value: customer

Example: "type": "customer"

Note: This field is case-sensitive. Follow the case as in the example when passing the value in the request.

customer_id String Yes The unique identifier is used to identify/create a user in MoEngage. Please refer to this section for more information on customer_id.
update_existing_only Boolean/String No

This field should be passed in the request when only existing users in MoEngage should be updated.

If this value is passed as true:

  1. Only those users for whom the customer_id from the request payload matches the customer identifier in MoEngage will be updated.
  2. In case of new users (customer_id in the payload does not match any of the existing customer ids in your MoEngage account), they will not be created.

If this value is passed as false:

  1. The user attributes will be updated with the values present in the payload for existing customers.
  2. In case of new users (customer_id in the payload does not match any of the existing customer ids in your MoEngage account), a new customer will be created in the system with the details specified in the payload.
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,
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 The 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 A 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 the set value is true.
platforms Not visible on the dashboard. List Value is 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.

Example Payload

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": "",
    "attributes": {
        "platforms" : [{"platform":"ANDROID","active":"true"}]


"id", "_id", and "" keywords are blocked and not to be used as user attribute names.
Was this article helpful?
2 out of 8 found this helpful

How can we improve this article?