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

# Update Global Control Group

> This API adds or removes users from the Global Control Group (GCG) in MoEngage. Provide a publicly accessible CSV of user IDs and specify whether to add or remove those users.


#### Rate Limit

The rate limit is 10 RPM.

<Note>
  * One file-processing request must complete before the next API call is accepted.
  * Currently, only publicly accessible Amazon S3 URLs are supported for `file_url`.
  * The Global Control Group must already be initialized with the **Upload Users** option before this API can be used. This API does not support the **Random allocation** option.
  * When the GCG base is successfully updated, subsequent runs of existing campaigns use the updated list.
  * Once file processing is completed, an email is sent to the user identified by `updated_by` summarizing the number of users successfully processed, the number of users that failed, and the possible reasons.
</Note>


## OpenAPI

````yaml /api/campaigns/campaigns.yaml put /global-control-group/users
openapi: 3.0.3
info:
  title: MoEngage Campaigns API
  version: '2025-11-20'
  description: >
    The MoEngage Campaigns API allows you to create and manage Push and Email
    campaigns programmatically.


    **Supported Channels:**

    - Push (Android, iOS, Web)

    - Email


    **Supported Delivery Types:**

    - ONE_TIME

    - PERIODIC

    - EVENT_TRIGGERED

    - BUSINESS_EVENT_TRIGGERED

    - DEVICE_TRIGGERED (Push only)

    - LOCATION_TRIGGERED (Push only)

    - BROADCAST_LIVE_ACTIVITY (Push iOS only)

     | Rate Limit Name | Rate Limit |
     | :--- | :--- |
     | Create campaign per second | The total number of create campaign operations per second per client allowed is 5. |
     | Create campaign per minute | The total number of create campaign operations per minute per client allowed is 25. |
     | Create campaign per hour | The total number of create campaign operations per hour per client allowed is 100. |

     You can create 5 campaigns per minute, 25 campaigns per hour, and 100 campaigns per day.

     <Note>
       * Breaching the limits will reject the request.
        * Per hour and per day limits will consider the calculation based on the last hour and last 24 hrs respectively.
     </Note>

    For more details, visit [MoEngage Developer
    Documentation](https://developers.moengage.com).
  contact:
    name: MoEngage Developer Team
    email: support@moengage.com
    url: https://developers.moengage.com
servers:
  - url: https://api-{dc}.moengage.com/core-services/v1
    description: MoEngage Campaigns 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: []
paths:
  /global-control-group/users:
    put:
      tags:
        - Update Campaigns
      summary: Update Global Control Group
      description: >
        This API adds or removes users from the Global Control Group (GCG) in
        MoEngage. Provide a publicly accessible CSV of user IDs and specify
        whether to add or remove those users.
      operationId: update_global_control_group
      parameters:
        - $ref: '#/components/parameters/MOE-APPKEY'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/GlobalControlGroupRequest'
            examples:
              add_users:
                summary: Add Users
                value:
                  request_id: '{{request_id}}'
                  file_url: https://example.csv
                  action_type: add
                  updated_by: john.doe@xyz.com
              remove_users:
                summary: Remove Users
                value:
                  request_id: '{{request_id}}'
                  file_url: https://example.csv
                  action_type: remove
                  updated_by: john.doe@xyz.com
      responses:
        '204':
          description: >-
            No Content - The request was processed successfully. There is no
            response body.
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '429':
          $ref: '#/components/responses/RateLimitExceeded'
        '500':
          description: >-
            Internal Server Error - An unexpected error occurred while
            processing this request.
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: object
                    properties:
                      title:
                        type: string
                        description: A short title for the error.
                      description:
                        type: string
                        description: A detailed, human-readable explanation of the error.
                      code:
                        type: string
                        description: Internal error code, if provided.
              example:
                error:
                  title: Server Error
                  description: >-
                    An unexpected error was encountered while processing this
                    request. Please contact Moengage team
                  code: <code>
components:
  parameters:
    MOE-APPKEY:
      name: MOE-APPKEY
      in: header
      required: true
      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)**.
      schema:
        type: string
      example: YOUR_WORKSPACE_ID
  schemas:
    GlobalControlGroupRequest:
      type: object
      description: Request to add or remove users from the Global Control Group (GCG).
      required:
        - request_id
        - file_url
        - action_type
        - updated_by
      properties:
        request_id:
          type: string
          description: Unique identifier of the request to update the Global Control Group.
          example: '{{request_id}}'
        file_url:
          type: string
          format: uri
          description: >
            Publicly accessible URL of the CSV file for processing. The file
            must contain a single column named `uid` followed by the respective
            user IDs in new rows. The file must be under 300 MB and downloadable
            without authentication.


            **Note:** Currently, only publicly accessible Amazon S3 URLs are
            supported.
          example: https://example.csv
        action_type:
          type: string
          enum:
            - add
            - remove
          description: The operation to perform on users in the Global Control Group.
        updated_by:
          type: string
          format: email
          description: The email ID of the user initiating the update.
          example: john.doe@xyz.com
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: The error code (e.g., "400 Bad Request").
            message:
              type: string
              description: Description of why the request failed.
            target:
              type: string
              description: The target of the error.
            details:
              type: array
              items:
                type: object
                properties:
                  target:
                    type: string
                  message:
                    type: string
            request_id:
              type: string
              description: The request ID associated with this error.
  responses:
    BadRequest:
      description: Bad Request - Missing or invalid parameters
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: 400 Bad Request
              message: request_id key is mandatory field
              target: request_id
              details:
                - target: request_id
                  message: request_id key is mandatory field
              request_id: '11'
    Unauthorized:
      description: Authentication Failure - Invalid or missing authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: 401 Authentication error
              message: Authentication required
              details:
                - code: InvalidValue
                  target: APP_SECRET_KEY
                  message:
                    - code: InvalidValue
                      target: APP_SECRET_KEY
                      message: Invalid APP_SECRET_KEY is provided.
              request_id: ''
    RateLimitExceeded:
      description: Rate Limit Breach - Too many requests
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: 429 conflict
              message: rate_limit
              target: ''
              details:
                - target: rate_limit
                  message: Rate limiting breached
              request_id: 3UXNNGsqV
  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
        **Campaign report/Business events/Custom templates/Catalog API/Inform
        Report** tile.


        For more information on authentication and getting your credentials,
        refer
        [here](https://www.moengage.com/docs/api/introduction#getting-your-credentials).

````