Overview

The MoEngage Cohort Sync API allows partners to synchronize cohorts or audiences created in their ecosystem with MoEngage.

The Cohort Sync API performs the following functions:

1. Creates a custom segment (Audience) in MoEngage. This custom segment can be utilized to create marketing campaigns on the MoEngage Dashboard.
2. Adds or removes a list of users who belong to a custom segment in MoEngage.
3. Dynamically updates the same custom segment created in MoEngage, ensuring that marketing campaigns automatically engage with the latest set of users during the next scheduled run.
4. It is important to note that the Cohort Sync API will only match users already present in MoEngage based on the user ID (uid) provided in the API request. This API will not create new users in MoEngage.

The Cohort Sync API enables the creation of segments without needing separate files or CSVs, eliminating the requirement for a separate path or URL as seen in the File Segment API. Segment creation can be initiated by making a direct server-to-server call, eliminating the additional steps required for generating user files. The Cohort Sync API is ideal for segments or segment operations involving fewer users.

User Resolution

The Cohort Sync API does not create new users in MoEngage. Instead, it resolves existing users in MoEngage based on predefined user identifiers and assigns them to the corresponding custom segment created through Cohort Sync. To achieve efficient user resolution, we primarily rely on the User ID. This identifier is provided by the clients and is set as a Unique User ID in MoEngage. It is typically available for registered or logged-in users. Each Unique User ID in MoEngage corresponds to a single user profile. Even if the same user is logged in from multiple devices, their user profile will have the same Unique User ID and the devices will be associated with that user profile. This identifier is represented as uid in the request payload.

API Endpoint

POST https://api-0X.moengage.com/v1/integrations/cohortsync

The 'X' in the API Endpoint URL refers to the MoEngage Data Center (DC). MoEngage hosts each customer in a different DC. 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 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

Parameters

Response

Response Codes

Rate Limit

The rate limits are:

1. 300 requests per minute
2. One payload per request (each payload can have multiple UIDs)
3. The payload size cannot exceed 128KB

Sample cURL for Adding Users using the API

curl --location 'https://api-0X.moengage.com/v1/integrations/cohortsync' \
--header 'MOE-APPKEY: {{MOE-APPKEY}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic e3tEQVRBIEFQSSBJRH19Ont7REFUQSBBUEkgS0VZfX0==' \
--data '{
    "action": "add_members",
    "partner": "6HNBXFm7ZS",
    "parameters": {
        "cohort_name": "<Partner_Name>",
        "cohort_id": "JKTAuqTRhC",
        "cohort_description": "<Cohort_Description>",
        "members": [
            {
                "uid": "mm1UR87z4T"
            },
            {
                "uid": "AtCxliflui"
            }
        ]
    }
}'

Sample cURL for Removing Users using the API

curl --location 'https://api-0X.moengage.com/v1/integrations/cohortsync' \
--header 'MOE-APPKEY: {{MOE-APPKEY}}' \
--header 'Content-Type: application/json' \
--header 'Authorization: Basic e3tEQVRBIEFQSSBJRH19Ont7REFUQSBBUEkgS0VZfX0==' \
--data '{
    "action": "remove_members",
    "partner": "6HNBXFm7ZS",
    "parameters": {
        "cohort_name": "<Partner_Name>",
        "cohort_id": "JKTAuqTRhC",
        "cohort_description": "<Cohort_Description>",
        "members": [
            {
                "uid": "mm1UR87z4T"
            }
        ]
    }
}'

Sample Response

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

Sample response for when idenitifers are missing in the request
{
    "status": "fail",
    "error": {
        "attribute": "identifiers",
        "message": "identifiers is not found in the payload",
        "type": "MissingAttributeError",
        "request_id": "UkBwaUmU"
    }
}

Sample response for when data is missing in the request
{
    "status": "fail",
    "error": {
        "attribute": "data",
        "message": "data is not found in the payload",
        "type": "MissingAttributeError",
        "request_id": "zAsmTigV"
    }
}

Sample response for when the JSON is incorrect in the request
{
    "status": "fail",
    "error": {
        "message": "Could not decode the request body. The JSON was incorrect or not encoded as UTF-8.",
        "type": "Malformed JSON",
        "request_id": "NphDCzWk"
    }
}

Sample response for when action is not found in the request
{
    "status": "fail",
    "error": {
        "attribute": "action",
        "message": "action is not found in the payload",
        "type": "MissingAttributeError",
        "request_id": "sYsoPuzf"
    }
}

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

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

Sample response for when there is a mismatch in the App Key
{
    "status": "fail",
    "error": {
        "message": "App key mismatch in params and authentication",
        "type": "Authentication Mismatch",
        "request_id": "yEujHykb"
    }
}

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

Postman Collections

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

FAQs

1. What is the difference between Cohort Sync API and the File Segment API?

The Cohort Sync API enables the creation of segments without needing separate files or CSVs, eliminating the requirement for a separate path or URL as seen in the File Segment API. Segment creation can be initiated by making a direct server-to-server call, eliminating the additional steps required for generating user files.

2. When is it recommended to use the Cohort Sync API?

The Cohort Sync API is ideal for segments or segment operations involving fewer users.

3. Does the Cohort Sync API create new users?

The Cohort Sync API does not create new users in MoEngage. Instead, it resolves existing users in MoEngage based on predefined user identifiers and assigns them to the corresponding custom segment created through Cohort Sync.