MoEngage Cohort Sync API

openapi: 3.2.0
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.
      x-mint:
        content: '<Info>

          * 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).

          </Info>


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

          '
      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:
    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'
    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'
    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'
    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
    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.
    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).

        '