Sync Cohort Members

This API adds or removes a list of users from a custom segment (cohort) in MoEngage.

POST /v1/integrations/cohortsync

cURL

AddMembers

curl --request POST \
  --url https://api-{dc}.moengage.com/v1/integrations/cohortsync \
  --header 'Authorization: Basic <encoded-value>' \
  --header 'Content-Type: application/json' \
  --header 'MOE-APPKEY: <moe-appkey>' \
  --data '
{
  "action": "add_members",
  "partner": "6HNBXFm7ZS",
  "parameters": {
    "cohort_name": ".Partner_Name",
    "cohort_id": "JKTAuqTRhC",
    "cohort_description": "A cohort of users from a partner.",
    "members": [
      {
        "uid": "mm1UR87z4T"
      },
      {
        "uid": "AtCxliflui"
      }
    ]
  }
}
'

200

Example

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

• The Cohort Sync API only matches users already present in MoEngage based on the User ID (uid) provided in the request. This API does not create new users.
• This API endpoint does not currently support Team-level scoping. All segments generated using this call will be assigned to the Default Team automatically.

Rate Limits

Please adhere to the following limits:

• Frequency: 300 requests per minute.
• Payload Structure: One payload per request (each payload can contain multiple UIDs).
• Size Limit: The payload size cannot exceed 128KB.

User Resolution

The Cohort Sync API resolves existing users in MoEngage based on predefined user identifiers:

• Identifier: We primarily rely on the User ID (uid) provided in the request payload.
• Matching: This must match the Unique User ID set in MoEngage (typically available for registered or logged-in users).
• Profile Association: Each Unique User ID corresponds to a single user profile. Even if a user is logged in across multiple devices, the devices are associated with that single user profile.

Authorizations

Authorization · string · header · required

Authentication is done via Basic Auth. This requires a base64-encoded string of your credentials in the format 'username:password'.

• Username: Use your MoEngage workspace ID (also known as the App ID). You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).
• Password: Use your API Key, which you can find within the Data tile.

For more information on authentication and getting your credentials, refer here.

Headers

MOE-APPKEY · string · required

This is the Workspace ID of your MoEngage account that must be passed with the request. You can find it in the MoEngage dashboard at Settings > Account > APIs > Workspace ID (earlier app id).

Body

application/json

The cohort details and the members to add or remove.

action · enum<string> · required

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

Available options: add_members, remove_members

partner · string · required

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

Example:

"6HNBXFm7ZS"

parameters · object · required

Contains the information about the cohort to be synced.

Show child attributes

Response

200

application/json

Success. This response is returned when the request is processed successfully.

Response body for a successful request.

status · string

The status of the request.

Example:

"success"

message · string

A message indicating the request was accepted.

Example:

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