Cohort/ Audience Sync

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

API Endpoint
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

Key Required Sample Values Description

MOE-APPKEY

Yes

{"MOE-APPKEY": "APP ID"}

This is your MoEngage account's APP ID that has to be passed along with the request. You can find your MoEngage APP ID in the following navigation on the Dashboard:

Revamped UI: Settings -> Account -> APIs -> App ID

Old UI: Settings -> API -> General Settings -> DATA API

Content-Type

Yes

application/json 

Set the Content-Type header to application/json.

Authorization

Yes

{"Authorization": "Basic bmF2ZWVua3VtYXI6bW9lbmdhZ2U=="}

This authentication parameter, used for access control, must be passed along with the request. To generate the authentication header, refer to Authentication.

Request Body

Key Required Data Type Description
action Yes String

This field indicates whether users need to be added to the cohort or removed from it.

Allowed Values: add_members, remove_members

Example: "action": "add_members"

partner No String

This field indicates the name of the partner whose cohort is being synced to MoEngage.

Example: "partner": "6HNBXFm7ZS"

parameters Yes JSON Object

This field contains the information about the cohort to be synced to MoEngage from the partner's ecosystem.

Structure:

"parameters": {
   "cohort_name": "<Cohort Name",
   "cohort_id": "<Cohort ID>",
   "cohort_description": "<Cohort description>",
  "members": [
    {
      "uid": "<UniqueIdentifier_customer1>"
    },
    {
      "uid": "<UniqueIdentifier_customer2>"

     }
  ]
}

For more details, refer to Parameters.

Parameters

Key Required Data Type Description
cohort_name Yes String

This field indicates the name of the cohort.

Example: "cohort_name": "Demo_Cohort"

cohort_id Yes String

This field indicates the unique identifier for the cohort being synced to MoEngage.

Example: "cohort_id": "Demo_CohortID"

cohort_description No String

This field contains the description for the cohort being synced to MoEnagage.

Example: "cohort_description": "This is a Demo Cohort to illustrate the addition and removal of cohorts to or from MoEngage."

members Yes Array of Objects

This field contains the unique identifiers of the customers being added to or removed from a Cohort in MoEngage.

Structure:

"members": [
    {
      "uid": "<UniqueIdentifier_customer1>"
    },
    {
      "uid": "<UniqueIdentifier_customer2>"

     }
  ]

Fields:

uid - This field indicates the unique identifier for a customer who is to be added or removed in MoEngage. For more information, refer to User Resolution.

Example:

 "members": [

   {

       "uid": "mm1UR87z4T"

    }

]

Response

Key Data Type Description

status

String

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

Supported Values: success, fail

Example: "status": "success"

message

String

This field is present in the response when the request is successful.

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

error

JSON Object

This field is present in the response only in the case of an error and contains the error details.

Structure:

{

   "attribute": "<attribute causing the error >",

   "message": "<error message>",

   "type": "<error type>",

   "request_id": "<request_id>"

}

 

attribute - This field contains the name of the request attribute causing the error. For example, "attribute": "identifiers" implies that the identifiers request attribute is causing the error.

message - This field contains the error message.

type - This field contains the error type. For example, "type": "Malformed JSON" implies that the JSON in the request is incorrectly formed.

request_id - This field denotes the request-id for which the error response is being returned. 

Response Codes

Status Code Request State Description

200

Success

This response is returned when the request is processed successfully. 

400

Bad Request

This response is returned when the required parameters APP KEY, user_id, and so on are missing from the request or when the provided params are invalid.

401

Authorization Failure

This response is returned when the authorization fails due to incorrect APP KEY/ HTTP Auth Header values. 

403

Account Suspended/Blocked Temporarily

This response is returned when the user account is temporarily suspended or blocked.

413

Payload Limit Exceeded

This response is returned when the payload size has exceeded the limit set.

415

Unsupported media type

This response is returned when the header “Content-Type” is not provided/is not supported.

429

Rate Limit Breach

This response is returned when the number of requests per minute has exceeded the rate limit.

5xx

Internal Server Error

This response is returned when the system runs into an unexpected error.

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

200 400 401 403 413 415 429 500
Success Response
{ "status": "success", "message": "Your request has been accepted and will be processed soon." }

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.

 

Previous

Next

Was this article helpful?
0 out of 0 found this helpful

How can we improve this article?