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

Method: POST

https://api-{{0X}}.moengage.com/v1/customer/{{appId}}

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.

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:

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.
3. Use these details to authenticate the API requests.

Request Parameters

Request Headers

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

Standard User Attributes

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

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"}]
    }
}

Reserved Keywords for User Attributes

Below is the list of keys that should not be used when tracking user attributes.

• USER_ATTRIBUTE_UNIQUE_ID
• USER_ATTRIBUTE_USER_EMAIL
• USER_ATTRIBUTE_USER_MOBILE
• USER_ATTRIBUTE_USER_NAME
• USER_ATTRIBUTE_USER_GENDER
• USER_ATTRIBUTE_USER_FIRST_NAME
• USER_ATTRIBUTE_USER_LAST_NAME
• USER_ATTRIBUTE_USER_BDAY
• USER_ATTRIBUTE_NOTIFICATION_PREF
• USER_ATTRIBUTE_OLD_ID
• MOE_TIME_FORMAT
• MOE_TIME_TIMEZONE
• USER_ATTRIBUTE_DND_START_TIME
• USER_ATTRIBUTE_DND_END_TIME
• MOE_GAID
• MOE_ISLATINSTALL
• statusUPDATE
• MOE_ISLAT
• user_idstatus
• user_id
• source

Response Codes

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

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

Missing authentication header
{
    "status": "fail",
    "error": {
        "message": "Authentication Header Required",
        "type": "Authentication required",
        "request_id": "PiSPjGQQ"
    }
}

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


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


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

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

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

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

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-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": {
        "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-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"}]
    }
}'

    

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.