curl --request POST \
--url https://api-{dc}.moengage.com/v1/customer/{app_id} \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "customer",
"customer_id": "[email protected]",
"attributes": {
"name": "JohnDoe",
"first_name": "John",
"platforms": [
{
"platform": "ANDROID",
"active": "true"
}
]
}
}
'{
"status": "success",
"message": "Your request has been accepted and will be processed soon."
}Track User
This API adds or updates users and user properties in MoEngage. You can create a new user, create new user property, or update existing user properties of users.
curl --request POST \
--url https://api-{dc}.moengage.com/v1/customer/{app_id} \
--header 'Authorization: Basic <encoded-value>' \
--header 'Content-Type: application/json' \
--data '
{
"type": "customer",
"customer_id": "[email protected]",
"attributes": {
"name": "JohnDoe",
"first_name": "John",
"platforms": [
{
"platform": "ANDROID",
"active": "true"
}
]
}
}
'{
"status": "success",
"message": "Your request has been accepted and will be processed soon."
}- For more information about trackable user attributes, reserved keys, and general data information, refer to the Data Overview.
- If you have Portfolio enabled for your workspace, you must pass
project_codein the API endpoint. This identifies which project a user or event belongs to. For more information, refer to Portfolio: Data Ingestion and Management. - Unsetting Attributes is an Early Access feature. To enable it for your account, contact your MoEngage Customer Success Manager (CSM) or the Support team.
Rate Limit
A single API request contains one or more user updates. Maintain a rate limit of 10,000 user updates per minute.Authorizations
Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.
- Username: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).
- Password: Use your API Key, which you can find within the Data tile.
Note: After you generate and save the Data API Key, DO NOT generate a new key unless there is a security breach. After you generate a different Data API key and save it, the authentication will start failing. You must update your existing data tracking.
For more information on authentication and getting your credentials, refer here.
Data APIs also support OAuth 2.0. For more information, refer to OAuth 2.0.
Headers
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.
"203.0.113.195"
Path Parameters
This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).
"VJ0GSMESHMQA3L7WV1EEK3UR"
Body
This is used to identify the type of request. The value is case-sensitive and must be lowercase (customer). A value with different casing, such as Customer, is not accepted.
customer The unique identifier is used to identify/create a user in MoEngage. Not mandatory in Identity Resolution enabled workspaces. 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"
}
}
```'
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.
A dictionary containing user attributes to add / update in the user profile. 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.
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. For other attributes that are not listed below, use the key-value pairs that you intend to use.
Array Support If you want to pass an attribute in an array, the appropriate syntax for that is:
"Array_attributeName":["abc","123"]
Update Array Attributes
To update an existing array attribute rather than overwrite it, use addValueToArrayField and removeValueFromArrayField inside the attributes object of a Track User call:
{
"customer_id": "user123",
"attributes": {
"addValueToArrayField": { "favorite_categories": ["shoes", "bags"] },
"removeValueFromArrayField": { "favorite_categories": ["hats"] }
}
}
addValueToArrayFieldappends the given value(s) to an existing array attribute.removeValueFromArrayFieldremoves the given value(s) from an existing array attribute.- You can't add and remove the same attribute in one call.
- You can't directly set an attribute and add/remove it in the same call.
- Reserved MoEngage attributes (e.g.
platforms) can't be used with these operators.
Show child attributes
Show child attributes
{
"name": "John",
"points": 20,
"expiry_date": "2020-05-31T03:47:35Z",
"super_user": true,
"user_persona": "browsers"
}
List of dictionaries with the associated platforms out of ANDROID, iOS, and web and their status.
Show child attributes
Show child attributes
Use this field to clear one or more existing user attributes. Add the name of each attribute you want to unset as a string in the array. Each name must exactly match the attribute name in your workspace. Attribute names that are not found are skipped without an error.
{
"customer_id": "user123",
"unset_attributes": ["first_name", "loyalty_tier"]
}
- System/reserved attributes are protected and can't be unset this way.