> ## Documentation Index > Fetch the complete documentation index at: https://moengage.com/docs/llms.txt > Use this file to discover all available pages before exploring further. # Sync Cohort Members > This API adds or removes a list of users from a custom segment (cohort) in MoEngage. * 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. * Please note that this API does not support updating cohorts created on the dashboard or via [File Segment API](https://www.moengage.com/docs/api/file-segments/create-file-segment). #### 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. ## OpenAPI ````yaml /api/cohort-audience/cohort-audience.yaml post /v1/integrations/cohortsync openapi: 3.0.3 info: title: Cohort Sync API description: >- The MoEngage Cohort Sync API allows partners to synchronize cohorts or audiences created in their ecosystem with MoEngage. It can add or remove users from a custom segment. version: 1.0.0 servers: - url: https://api-{dc}.moengage.com description: MoEngage API Server variables: dc: default: '01' description: >- The ‘dc’ 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 and replace the value of ‘dc’ in the URL by referring to the DC and API endpoint mapping [here](/api/introduction#data-centers). Your MoEngage Data Center (DC) can be 01, 02, 03, 04, 05, 06, or 101. security: - basicAuth: [] tags: - name: Cohort Sync description: Operations to synchronize cohorts (custom segments) with MoEngage. paths: /v1/integrations/cohortsync: post: tags: - Cohort Sync summary: Sync Cohort Members description: >- This API adds or removes a list of users from a custom segment (cohort) in MoEngage. parameters: - in: header name: MOE-APPKEY required: true schema: type: string description: >- 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)**. requestBody: description: The cohort details and the members to add or remove. required: true content: application/json: schema: $ref: '#/components/schemas/CohortSyncRequest' examples: AddMembers: summary: Add users to a cohort value: 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 RemoveMembers: summary: Remove users from a cohort value: action: remove_members partner: 6HNBXFm7ZS parameters: cohort_name: Partner_Name cohort_id: JKTAuqTRhC cohort_description: A cohort of users from a partner. members: - uid: mm1UR87z4T responses: '200': description: >- Success. This response is returned when the request is processed successfully. content: application/json: schema: $ref: '#/components/schemas/CohortSyncSuccess' example: status: success message: Your request has been accepted and will be processed soon. '400': description: >- Bad Request. This response is returned when the required parameters (APP KEY, user_id, etc.) are missing from the request or when the provided params are invalid. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: MissingIdentifiers: summary: Identifiers missing in request value: status: fail error: attribute: identifiers message: identifiers is not found in the payload type: MissingAttributeError request_id: UkBwaUmU MissingData: summary: Data missing in request value: status: fail error: attribute: data message: data is not found in the payload type: MissingAttributeError request_id: zAsmTigV MissingAction: summary: Action missing in request value: status: fail error: attribute: action message: action is not found in the payload type: MissingAttributeError request_id: sYsoPuzf MalformedJson: summary: JSON is incorrect value: 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 '401': description: >- Authorization Failure. This response is returned when the authorization fails due to incorrect APP KEY/ HTTP Auth Header values. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: AppSecretMismatch: summary: App Secret Key Mismatch value: status: fail error: message: >- App Secret key mismatch. Please login to the dashboard to verify key type: Authentication required request_id: skSFWvtW MissingAuthHeader: summary: Missing Authentication Header value: status: fail error: message: Authentication Header Required type: Authentication required request_id: PiSPjGQQ AppKeyMismatch: summary: App Key Mismatch value: status: fail error: message: App key mismatch in params and authentication type: Authentication Mismatch request_id: yEujHykb '403': description: >- Account Suspended/Blocked Temporarily. This response is returned when the user account is temporarily suspended or blocked. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: BlockedClient: summary: Account Blocked value: status: fail error: message: Your account is suspended. Please contact MoEngage team. type: BlockedClient request_id: ofHUEaEQ AccountSuspended: summary: Account Suspended value: status: fail error: message: Your account is suspended. Please contact MoEngage team. type: Account Suspended request_id: gqJvCNYu AccountTemporarilySuspended: summary: Account Temporarily Suspended value: status: fail error: message: >- Your account is temporarily suspended. Please contact MoEngage team. type: Account Temporarily Suspended request_id: ssSJjoyD '413': description: >- Payload Limit Exceeded. This response is returned when the payload size has exceeded the limit set (128KB). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: fail error: message: Payload can not exceed 128KB type: Payload too large request_id: VFzDwhwt '415': description: >- Unsupported media type. This response is returned when the header “Content-Type” is not provided/is not supported. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: fail error: message: Content type is not supported type: Unsupported media type request_id: SgBQfKJh '429': description: >- Rate Limit Breach. This response is returned when the number of requests per minute has exceeded the rate limit (300/min). content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: fail error: message: >- Rate limits for customers exceeded. Please Try After Some Time type: Rate Limits Exceeded request_id: onqucLYL '500': description: >- Internal Server Error. This response is returned when the system runs into an unexpected error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: status: fail error: message: >- An unexpected error was encountered while processing this request. Please contact MoEngage Team type: Server Error request_id: KovrwJiF components: schemas: CohortSyncRequest: type: object required: - action - partner - parameters properties: action: type: string description: >- This field indicates whether users need to be added to the cohort or removed from it. enum: - add_members - remove_members partner: type: string description: >- This field indicates the name of the partner whose cohort is being synced to MoEngage. example: 6HNBXFm7ZS parameters: $ref: '#/components/schemas/CohortParameters' CohortSyncSuccess: type: object description: Response body for a successful request. properties: status: type: string description: The status of the request. example: success message: type: string description: A message indicating the request was accepted. example: Your request has been accepted and will be processed soon. ErrorResponse: type: object description: Generic error response schema. properties: status: type: string description: The status of the request. example: fail error: $ref: '#/components/schemas/ErrorDetails' CohortParameters: type: object description: Contains the information about the cohort to be synced. required: - cohort_name - cohort_id - members properties: cohort_name: type: string description: >- The name of the cohort. Note: Ensure your cohort name must not start with a period (.) and must not contain the restricted characters pipe (|), asterisk (*), question mark (?), backward slash (\), colon (:), open angle bracket (<), closed angle bracket (>), equal sign (=), dollar sign ($), double-quotation mark ("). example: Demo_Cohort cohort_id: type: string description: The unique identifier for the cohort being synced to MoEngage. example: Demo_CohortID cohort_description: type: string description: A description for the cohort being synced to MoEngage. example: This is a Demo Cohort. members: type: array description: >- Contains the unique identifiers of the customers being added to or removed from a Cohort in MoEngage. items: $ref: '#/components/schemas/CohortMember' ErrorDetails: type: object description: Details of the error that occurred. properties: attribute: type: string description: The request attribute causing the error. example: action message: type: string description: A human-readable error message. example: action is not found in the payload type: type: string description: The type of error. example: MissingAttributeError request_id: type: string description: A unique ID for tracing the request. example: UkBwaUmU CohortMember: type: object required: - uid properties: uid: type: string description: >- The unique identifier (Unique User ID) for a customer who is to be added or removed. example: mm1UR87z4T securitySchemes: basicAuth: type: http scheme: basic description: > 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](https://www.moengage.com/docs/api/introduction#getting-your-credentials). ````