Track User

Overview

User API helps add or update users and user properties in MoEngage.

Use cases:

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

API Endpoint

POST https://api-0X.moengage.com/v1/customer/<Workspace_ID>

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage maintains different data centres for different clients. 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.

info	Note The Workspace_ID for your MoEngage account is available on the MoEngage Dashboard at Settings -> Account -> APIs -> Workspace ID.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username:password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization: Basic Base64_ENCODED_WORKSPACEID_APIKEY=="}

The username and password details can be obtained from the MoEngage Dashboard. If you're using the API for the first time, follow these steps:

Navigate to Settings -> Account -> APIs.
Copy the following details:
- Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Data tile to copy the API key.
Use these details to authenticate the API requests.

Request Parameters

Key	Mandatory/Optional	Data String	Description
app_id	Mandatory	String	This is your MoEngage account's Workspace ID that has to be passed along with the request. You can find your Workspace ID at Settings > Account > APIs > Workspace ID.

Request Headers

Key	Mandatory/Optional	Sample Values	Description
Content-Type	Mandatory	{"Content-Type": "application/json"}	Set the Content-Type header to application/json.
Authorization	Mandatory	{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}	This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.
X-Forwarded-For	Optional	Header Value Format: <IP Address>	The 'X-Forwarded-For' header is used to specify the IP address of the client that made the request. This header may be added by proxy servers or load balancers. The header value must contain the IP address of the original client that initiated the request. Multiple IP addresses may be specified in the header value, separated by commas.

Request Body

A sample request body is described for the user with the unique id john@example.com.

{
"type": "customer",
"customer_id": "john@example.com",
"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. 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. Not mandatory in Identity resolution enabled workspaces.
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: Only those users for whom the customer_id from the request payload matches the customer identifier in MoEngage will be updated. 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: The user attributes will be updated with the values present in the payload for existing customers. 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.

info	Information In the MoEngage platform, the standard attributes are identified when an attribute has (standard) marked right next to it - for example, email(standard).

Key	Attribute Name on Dashboard	Datatype	Description
u_n	Name	String	Full name of the user.
u_fn	First Name	String	First name of the user.
u_ln	Last Name	String	Last name of the user.
u_gd	Gender	String	The gender of the user.
u_em	Email (Standard)	String	Email Address of the user. For example, john@example.com
u_mb	Mobile Number (Standard)	String	Mobile Number of the user. For example, 918888444411
uid	ID	String	A unique ID that the app has set for a user. This is a standard attribute where MoEngage provides the name, and the value is provided by the client.
u_bd	Birthday	Date	The birthdate of the user. Information in ISO 8601 format. For example: 2019-05-21T03:47:35Z
moe_wa_subscription	WhatsApp Subscription Status	Boolean	The WhatsApp subscription status of a user - True / False.
moe_em_unsub_categories	Email Unsubscribed Categories	String	The List of email categories user has unsubscribed.
push_preference	Push Opt In Status (iOS)	Boolean	Push permission status of a user on an iOS device.
moe_sub_w	Web Push Subscription Status	Boolean	The web push subscription status of a user - True / False. Use it to find your aggregate subscribers and users who unsubscribed after subscribing once.
moe_spam	Spam	Boolean	Email Spam Attribute. The emails are not sent to the user when the set value is true.
moe_unsubscribe	Unsubscribe	Boolean	Email Unsubscribe Attribute. Emails are not sent to the user when the set value is true.
moe_hard_bounce	Hard Bounce	Boolean	Email Hard Bounce Attribute. The emails are not sent to the user when the set value is true.
moe_sms_subscription	SMS Subscription Status	String	An attribute which stores the SMS subscription status of the user. This will be used to see if a user is reachable based on certain values of the attribute.
moe_email_optin_status	Email Opt-in Status	String	An attribute that stores the opt-in status of the user for the email channel. Supported values are: DOUBLE_OPTED_IN OPTED_OUT OPT_IN_PENDING

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": "john@example.com",
    "update_existing_only":"true",
    "attributes": {
        "points":20,
        "expiry_date":"2020-05-31T03:47:35Z",
        "super_user":true,
        "user_persona":"browsers",
        "platforms" : [{"platform":"ANDROID","active":"true"}]
    }
}

info	Note "id", "_id", and "" keywords are blocked and not to be used as user attribute names. You can not use "moe_" as a prefix while naming user attributes. It is a system prefix and using it might result in periodic blacklisting without prior communication.

Response Codes

Status Code	Request State	Description
200	Success	This response is returned when the request is processed successfully.
400	Bad Request	This response is returned when the required parameters are missing from the request, attributes are not found, and incorrect values are passed.
401	Unauthorized	This response is returned when the request does not have valid authentication credentials.
403	Account Blocked	This response is returned when your MoEngage account is suspended or blocked.
413	Payload Size Exceeded	This response is returned when the payload size exceeds 128 KB.
415	Unsupported Media Type	This response is returned when the content type is not supported.
429	Rate Limit Breach	This response is returned when the number of requests has exceeded the rate limit.
500	Internal Server Error	This response is returned when the system runs into an unexpected error.

Sample Response

Success Response
{
    "status": "success",
    "message": "Your request has been accepted and will be processed soon." 
}

Customer ID is missing in the payload
{
    "status": "fail",
    "error": {
        "attribute": "customer_id",
        "message": "customer_id is not found in the payload",
        "type": "MissingAttributeError",
        "request_id": "ZbPXtKFL"
    }
}

Customer ID is empty: 
{
    "status": "fail",
    "error": {
        "attribute": "customer_id",
        "message": "customer_id can not be empty Unicode String",
        "type": "MissingAttributeError",
        "request_id": "VgjtlxTu"
    }
}

Array field error: 
{
    "status": "fail",
    "error": {
        "attribute": "addValueToArrayField",
        "message": "Cannot add and remove 'first_name' at the same time",
        "type": "ArrayFieldError",
        "request_id": "WPDAbugh"
    }
}

Sample response for authorization errors
{
    "status": "fail",
    "error": {
        "message": "App Secret key mismatch. Please login to the dashboard to verify key",
        "type": "Authentication required",
        "request_id": "PVUDFisO"
    }
}

Sample response for missing authentication header
{
    "status": "fail",
    "error": {
        "message": "Authentication Header Required",
        "type": "Authentication required",
        "request_id": "PiSPjGQQ"
    }
}

Sample response for when your account is blocked
{
    "status": "fail",
    "error": {
        "message": "Your account is suspended. Please contact MoEngage team.",
        "type": "BlockedClient",
        "request_id": "ofHUEaEQ"
    }
}


Sample response for when your account is suspended
{
    "status": "fail",
    "error": {
        "message": "Your account is suspended. Please contact MoEngage team.",
        "type": "Account Suspended",
        "request_id": "gqJvCNYu"
    }
}


Sample response for when your account is temporarily suspended
{
    "status": "fail",
    "error": {
        "message": "Your account is temporarily suspended. Please contact MoEngage team.",
        "type": "Account Temporarily Suspended",
        "request_id": "ssSJjoyD"
    }
}

Sample response for payloads exceeding the size limit
{
    "status": "fail",
    "error": {
        "message": "Payload can not exceed 128KB",
        "type": "Payload too large",
        "request_id": "VFzDwhwt"
    }
}

Sample response for unsupported media type
{
    "status": "fail",
    "error": {
        "message": "Content type is not supported",
        "type": "Unsupported media type",
        "request_id": "SgBQfKJh"
    }
}

Sample response for rate limit breach
{
    "status": "fail",
    "error": {
        "message": "Rate limits for customers exceeded. Please Try After Some Time",
        "type": "Rate Limits Exceeded",
        "request_id": "onqucLYL"
    }
}

Sample response for unknown errors
{
    "status": "fail",
    "error": {
        "message": "An unexpected error was encountered while processing this request. Please contact MoEngage Team",
        "type": "Server Error",
        "request_id": "KovrwJiF"
    }
}

Sample cURL Request

curl --location --request POST 'https://api-01.moengage.com/v1/customer/<Workspace_ID>' \
--header 'Content-Type: application/json' \
--header ''Basic {{Authorization_Key}}' \
--data-raw '{
 
  "type": "customer",
 
  "customer_id": "123",
 
  "attributes": {
 
    "name": "JohnDoe",
 
    "first_name": "John",
 
    "platforms": [
 
      {
 
        "platform":"iOS",
 
        "active": "true"
 
      }
 
    ]
 
  }

}'

Array Support

If you want to pass an attribute in an array, the appropriate syntax for that is:

"Array_attributeName":["abc","123"],

The sample cURL for adding and removing elements in an array is:


curl --location --request POST 'https://api-01.moengage.com/v1/customer/<Workspace_ID>\
--header 'Content-Type: application/json' \
--header 'Basic {{Authorization_Key}}' \
--data-raw '{
"type" : "customer",
"customer_id": "123",
    "attributes": {
        
        "removeValueFromArrayField": {
            
            },

        "addValueToArrayField": {
                "attribute1":["abc","def"],
                "attribute2":["a"],
                "attribute3":["123"]
            },
            
        "platforms" : [{"platform":"iOS", "active":"true"}]
    }
}'

User Identity Resolution

If the User Identity Resolution feature is enabled in your workspace, the attribute parameters in the payload must contain at least one of the identifiers you have activated in your workspace based on which users in MoEngage will be created, updated, or merged.

In the following example, moe_mobile is one of the identifiers in the workspace and is passed in attributes:

 {
        "type": "customer",
        "attributes": {"moe_mobile": "{{Mobile_Number}}",
        "first_name": "John" 
      }
},

For more information, refer to User Identity Resolution.

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

How do we reduce the 5xx errors because of too many requests per second/minute?
Please attempt exponential backoff of requests to ensure there is no data loss due to 5xx errors.
How do I know if my user data has been ingested into MoEngage?
Getting a 200 status code as a response from MoEngage only indicates that the users in your API payload have been accepted for processing. It does not ensure that the users sent to MoEngage have been successfully ingested.
Although, this happens very rarely and you can search for newly ingested users in:
Segment > Create Segment > Search for users using their IDs
Can I use this API to also export users?
Please use the Get User API to export the users.
Can I use this API to delete users from MoEngage?
Please use the Delete User API to delete existing users in MoEngage.