Bulk Update Preferences API helps you update the users' subscription preferences in batch mode.

API Endpoint

POST https://api-0X.moengage.com/v1/category-subscription/user-preferences

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

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

The username and password details can be obtained from the MoEngage Dashboard. We've revamped the settings UI in the Dashboard. If you're using the API for the first time, follow these steps for the revamped and old UIs:

Revamped UI

1. Navigate to Settings -> Account -> APIs.
2. Click Generate Key in the Data tile in the API Keys section, and click Save.
3. Use the Workspace ID as the username and the Data API Key as the password to generate the authentication header.

Old UI

1. Navigate to Settings -> APIs -> DATA API Settings.
2. Click Generate Key.
3. Click Save on the Data APIs settings section. 
4. Use the DATA API ID as the username and the DATA API KEY as the password to generate the authentication header.

Request Headers

Request Body

Data Object

The data object contains the subscription preferences of the users. It contains the following fields:

• customer_id
  This string contains the unique identifier denoting the customer for whom you are updating the subscription preferences. This is the ID on the user profile page.
• categories
  This is a JSON Object that contains the subscription preferences of the customer.
•  unsubscribe_all
  This field contains information about whether or not a customer has unsubscribed from all categories. When unsubscirbe_all is true, the user is unsubscribed from all the categories, irrespective of the categories marked as true in the category JSON object. The Unsubscribe user property in the User Profile gets updated to true.

Response Parameters

Response Codes

Rate Limit

The rate limit is 100 RPM and 360k per day.

Sample cURL Request

curl --location -g --request POST 'https://api-{{0X}}.moengage.com/v1/category-subscription/user-preferences' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{DATA Workspace ID}}' \
--header 'Authorization: Basic e3tEQVRBIEFQSSBJRH19Ont7REFUQSBBUEkgS0VZfX0=' \
--data-raw '{
    "channel": "email",
    "user_preferences": [
    {
	 "customer_id": "john@example.com",
	 "categories": {
            "Promotional": false,
            "Transactional": false,
            "Special Offers": true
         },
         "unsubscribe_all": false
     },
     {
     	 "customer_id": "mike@example.com",
         "categories": {
            "Transactional": true,
            "Promotional": false,
            "Special Offers": true
         },
         "unsubscribe_all": false
      },
      {
      	  "customer_id": "doe@example.com",
          "categories": {
              "Product Updates": true,
              "New arrivals": false,
              "Recommendations": true
           },
           "unsubscribe_all": false
       }
    ]
 }'

Sample Response

Success Response
{
    "message": "Your request has been processed"
}

Sample Response for Bad Requests 
{
    title="Categories Required", 
    description="Categories Preferences Required" 
}

Sample Response for Requests that have exceeded the Payload Limit
{
    title="Payload Limit Exceeded", 
    description="Payload limit is set to 50"
}

Sample Response for Authorization Errors
{
    "title": "Authentication required",
    "description": "No identity information found.
}

Sample Response for Authorization Errors
{
    "title": "Header required",
    "description": "MOE-APPKEY missing in Header"
}

Sample Response for Rate Limit Breach
{
     title="Rate-Limit Reached", 
     description="Exceeded rate limit for this url"
}

Sample Response for Unknown Errors
{
	"title": "Internal Error",
	"description": "Please Contact Moengage Team"
}

Postman Collections

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

FAQs

• What is the batch size for the bulk update?
  The maximum batch size is 50.