Introduction 

The MoEngage Cohort Sync API will enable partners to sync cohorts/audiences created on the partner side with MoEngage.

The Cohort Sync API will -

1. Create a custom segment (Audience) in MoEngage, which MoEngage dashboard customers can use for creating marketing campaigns (push, in-app, email, SMS, etc.).
2. Add / Remove a users/list of users under a custom segment in MoEngage
3. Dynamically update the same custom segment created in MoEngage so that the marketing campaigns automatically engage the latest set of users on the next scheduled run.
4. The Cohort Sync API will only resolve users already present in MoEngage basis on the user_id received in the API request. The Cohort Sync API will not create new users in MoEngage.

Sync Types

1. One-Time: This will create a custom segment in MoEngage from a partner cohort/audience and place a list of users under the custom segment. The custom segment in MoEngage will not change. 
   
2. Periodic: This will keep on synchronizing the users under a partner cohort/audience with a MoEngage Custom Segment so that the latest set of users in the partner cohort/audience are also present in the corresponding MoEngage segment 

User Resolution

The Cohort Sync API will not create new users in MoEngage but will instead resolve users existing in MoEngage basis pre-defined user identifiers and place the resolved users under the corresponding custom segment created in MoEngage due to the Cohort Sync. 

For effective user resolution, we usually depend upon 1-2 different identifiers -

1. User Id:  This will be available for the registered / logged-in users. This is defined by the clients and should be set as Unique User Id in MoEngage.
   In MoEngage every Unique User Id will identify a single user profile. If the same user is logged-in from multiple devices, we will still have a single user profile with the Unique User Id and map multiple devices to this user profile. This is represented as uid in the request payload.
   
2. Anonymous_id:  This will be available for non-registered / non logged-in users. This needs to be present in the MoEngage user profiles and partner user profiles and will be used to resolve users in MoEngage in case the User Id is not available.
   

Configurations

For the API integration to be effective for all customers, we would need to support the following configurations on the partner side for maximum customer impact 

1. APP_ID:  This represents the MoEngage Account ID of the Client. This is available on the MoEngage Dashboard (Settings -> App -> General -> APP ID)
   
2. Secret Key: This will be used to Authenticate the API requests and the value for Secret Key is available on MoEngage dashboard. (Settings -> App -> API -> Data API Key)
   
3. Data Center:  This will be used to identify the MoEngage Data Center that the client is signed up on. Depending upon the data residency requirements by the client, they may be signed up with one of the MoEngage Data Centers - DC-01, DC-02, or DC-03.
   
4. uid: This will be the primary identifier used to resolve users in MoEngage.
   
5. anonymous_id:   This will be the secondary identifier used to resolve users in MoEngage when User Id is not available.

API Details

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.

Headers

Authentication: We accept Base 64 encoded username:password where username is the APP_ID and password is the Secret Key (specified in the previous section)

Request

Adding users to a cohort (audience)

{	
    "action": "add_members",
    "timestamp": "",
    "partner": "",
    "parameters": {
        "cohort_name": "",
	      "cohort_id": "",
	      "cohort_description": "cohort_description",
	      "members": [
		        {"uid": "","" : ""}
		    ]
    }
}

Removing users from a cohort (audience)

{
    "action": "remove_members",
    "timestamp": "",
    "partner": ""
    "parameters": {
        "cohort_name": "",
	      "cohort_id": "",
	      "cohort_description": "cohort_description",
	      "members": [
            {"uid": "", "" : ""}
		     ]
    }
}

Fields

It is mandatory to have at least one of uid or anonymous_id in the payload. If both are present, we will first use uid to resolve a user and if not user is available, will try to resolve a user basis the anonymous_id