Track User

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

POST /customer/{app_id}

cURL

sample_cURL

curl --request POST \ --url https://api-0{dc}.moengage.com/v1/customer/{app_id} \ --header 'Authorization: Basic <encoded-value>' \ --header 'Content-Type: application/json' \ --data ' { "type": "customer", "customer_id": "[e-mail]", "attributes": { "name": "JohnDoe", "first_name": "John", "platforms": [ { "platform": "ANDROID", "active": "true" } ] } } '

200

success_response

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

Use cases:

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

If you have Portfolio enabled for your workspace, you need to pass project_code in the API endpoint. This identifies which project a user or event belongs to. For more information, refer to Portfolio: Data Ingestion and Management.

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-0X.moengage.com/v1/customer/{{appId}}?app_id={{appId}}'\
--header 'Content-Type: application/json' \
--header {"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"} \
--data-raw '{
      "type": "customer",
      "customer_id": "123",
      "attributes": {

        "removeValueFromArrayField": {
  
             },

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

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.

Authorizations

Authorization · string · header · required

This authentication parameter, used for access control, must be passed along with the request. 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:

1. Navigate to Settings -> Account -> APIs.
2. 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.

Headers

X-Forwarded-For · string

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.

Example:

"203.0.113.195"

Path Parameters

app_id · string · required

This is the Workspace ID of your MoEngage account that has to be passed along with the request. You can find your Workspace ID at Settings > Account > APIs > Workspace ID.

Example:

"VJ0GSMESHMQA3L7WV1EEK3UR"

Body

application/json

type · enum<string> · required

This is used to identify the type of request. This field is case-sensitive. Follow the case as in the example when passing the value in the request.

Available options: customer

customer_id · string · required

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" 
      }
}
```' 

update_existing_only · boolean · default: false

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 · object

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.

Show child attributes

Example:

{
  "name": "John",
  "points": 20,
  "expiry_date": "2020-05-31T03:47:35Z",
  "super_user": true,
  "user_persona": "browsers"
}

platforms · object[]

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

Show child attributes

Response

200

application/json

This response is returned when the request is processed successfully.

status · string

This field contains the status of the request and specifies whether the request was successful.

Example:

"success"

message · string

Example:

"Your request has been accepted and will be processed soon."