Global Control Group API

You can use this API to add and remove users to the Global Control Group (GCG) request in MoEngage.

API Endpoint

Method: PUT

https://api-0X.moengage.com/core-services/v1/global-control-group/users

Each customer is hosted on a different data center; you can find your data center number (value of X) by checking the data center and API endpoint mapping page.

Authentication

The API request will be authenticated through Basic Authentication. Basic Authentication sends a Base64-encoded string containing your username and password with every API request. It encodes a 'username: password' string in Base64 and appends the encoded string with 'Basic '. This string is included in the authorization header as shown below:

{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}

You can obtain the username and password details from the MoEngage UI.

Navigate to Settings -> Account -> APIs.
Copy the following details:
- Username: Under Workspace ID (earlier app id), click the copy icon to copy the username.
- Password: In the API keys section, click the copy icon in the Campaign report/Business events/Custom templates tile to copy the API key.
Use these details to authenticate the API requests.

Request Headers

Key	Required	Sample Values	Description
Content-Type	Required	{"Content-Type": "application/json"}	Set the Content-Type header to application/json.
Authorization	Required	{"Authorization": "Basic Base64_ENCODED_APPKEY_APIKEY"}	This authentication parameter, used for access control, must be passed in the request. To generate the authentication header, refer to Authentication.
MOE-APPKEY	Required	{“MOE-APPKEY”: “Workspace ID”}	This is the workspace ID (earlier APP ID) of your MoEngage workspace. The MOE-APPKEY has to be passed in the request. You can find your MoEngage Workspace ID in the MoEngage UI: Settings -> Account -> APIs -> Workspace ID (earlier app id) For more information, refer to Authentication.

Request Body

Key	Required	Values	Description
request_id	Required	String	This field denotes the request ID that you must pass to update the Global Control Group.
file_url	Required	String	This field denotes the 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. Additionally, the file must be under 300 MB in size and downloadable without requiring authentication.
action_type	Required	String	This field denotes the operation to perform on users in the global control group. Supported values are add and remove.
updated_by	Required	String	This field denotes the email ID of the user.

Response

Key

Data Type

Description

error

JSON Object

This field contains the reason for the request's failure.

Structure:

{

"error": {

"message": "<error_message>",

"details": [

{

"target": "<target>",

"message": "<error_message>"

}

The error object contains the following fields:

message - This field is of String type and describes why the request has failed.
details - This object provides the error details and contains the following information:
- target - This field is of String type and denotes the target of the error.
- message - This field is of String type and describes why the request has failed.

Response Codes

Status Code	Request State	Description
204	No Content	This code denotes success. There won't be any response body for this.
400	Bad Request	This response is returned when the required parameters are missing from the request or when the provided parameters are invalid.
401	UnAuthorized	This response is returned when the authorization parameters are missing in the HTTP Auth Header.
429	Rate Limit Breach	This response is returned when the number of requests per minute has exceeded the rate limit.
500	Internal Server Error	This response is returned when the system runs into an unexpected error.

Rate Limit

The rate limit is 10 RPM.

Sample cURL Request

curl --location 'https://api-0X.moengage.com/core-services/v1/global-control-group/users' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data-raw '{
    "request_id": "{{request_id}}",
    "file_url": "https://example.csv",
    "action_type": "add",
    "updated_by": "john.doe@xyz.com"
}'

curl --location 'https://api-0X.moengage.com/core-services/v1/global-control-group/users' \
--header 'accept: application/json' \
--header 'Content-Type: application/json' \
--header 'MOE-APPKEY: {{Workspace_ID or APP_ID}}' \
--header 'Authorization: Basic {{Authorization_Key}}' \
--data-raw '{
    "request_id": "{{request_id}}",
    "file_url": "https://example.csv",
    "action_type": "remove",
    "updated_by": "john.doe@xyz.com"
}'

Sample Response

[]

{
    "error": {
        "message": "request_id key is mandatory field",
        "target": "request_id",
        "details": [
            {
                "target": "request_id",
                "message": "request_id key is mandatory field"
            }
        ],
    }
}

{
    "error": {
        "message": "Invalid Request",
        "details": [
            {
                "target": "action_type ",
                "message": "action_type - Field is required but value is None : None"
            }
        ]
    }
}

{
    "error": {
        "message": "rate_limit",
        "target": "",
        "details": [
            {
                "target": "rate_limit",
                "message": "Rate limiting breached"
            }
        ],
    }
}

{
    "error": {
        "title": "Server Error",
        "description": "An unexpected error was encountered while processing this request. Please contact Moengage team",
        "code": "<code>"
         }
 }

Postman Collections

We have made it easy for you to test the APIs. Click here to view it in Postman.

FAQs

arrow_drop_down Can I do multiple calls simultaneously for Add and remove of users?

No, one file processing should be completed, and then only the next API call will be accepted.

arrow_drop_down Can I share the public url for any cloud provider such as Azure, Google cloud storage, etc?

No, currently only Amazon S3 public url is supported by this api.

arrow_drop_down Will I get to know the detailed processing status of the file?

Yes, once the file processing is completed, you will get an email at the email ID mentioned in the API call. This email will indicate the number of users successfully processed, the number of users failed and the possible reasons.

arrow_drop_down What should be the content of the file for the Global control group?

It should contain one column with column name as "uid" followed with ID/uid of respective user in new row.

arrow_drop_down Can I create the Global Control Group (GCG) base if the initial setup is incomplete?

No. You must select Upload Users settings and upload the initial GCG base before you can use this API.

arrow_drop_down Can I add or remove users from the "Random allocation" option in GCG?

No. This API only supports adding or removing users if the GCG is configured for the Uploading User list option.

arrow_drop_down How does updating the GCG base affect existing campaigns?

When the API successfully updates the GCG base, any new runs of existing campaigns immediately use the updated list. For example, if you add a user to the GCG base who previously received campaigns, that user will stop receiving campaigns in future campaign runs.