# Creates a dynamic custom group with criteria-based membership Creates a dynamic custom group (`groupCategory=2`) where members are automatically populated based on filter criteria. Only computer-type dynamic groups are supported — user-type dynamic groups are not allowed. **Required:** `groupName`, `groupType=1`, `groupCategory=2`, `criteriaList`, `criteriaPattern`. `criteriaList` is a linear ordered array of filter criteria (1-based positional indices). `criteriaPattern` is a separate combinator expression (e.g. `'1'`, `'1 AND 2'`, `'(1 OR 2) AND 3'`) that declares how the entries of `criteriaList` are combined — it is mandatory; the server rejects requests with a missing or empty `criteriaPattern` (error code `70503`). Each criteria entry needs `columnId`, `logicalOperator`, `comparator`, and `criteriaValue`. **Prerequisites:** 1. Call [Get Dynamic CG Criteria Pattern](https://www.manageengine.com/products/desktop-central/custom-groups-get-dynamic-cgcriteria-pattern.html) to discover available columns and operators. 2. Call [Get Dynamic CG Column Values](https://www.manageengine.com/products/desktop-central/custom-groups-get-dynamic-cgcolumn-values.html) to fetch valid comparison values for each column. 3. Build `criteriaList` using the discovered `columnId`, `comparator`, and `criteriaValue`, then build `criteriaPattern` using 1-based indices into `criteriaList`. ## Endpoints **POST** `/api/1.4/customgroup/addCg` --- ## Request URL ``` https://{serverurl}/api/1.4/customgroup/addCg ``` `{serverurl}`: See [OAuth Authentication - Endpoint Domain](https://www.manageengine.com/products/desktop-central/oauth-authentication-endpoint-domain.html) ## Scope ``` DesktopCentralCloud.Common.UPDATE ``` ## Header ``` Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52 ``` ## Request Parameters ### Request Headers #### Content-Type (string) — Mandatory `application/json` Must be application/json. Request body must be valid JSON. #### Accept (string) — Mandatory `application/json` Must be application/json. Only JSON responses are supported. ### Request Body — application/json JSON object #### groupName (string) — Mandatory Name for the new group. Must be unique. Max 100 chars. Forbidden characters: ``` ` \ : ; < > ? * " | & # % / ``` #### groupCategory (string) — Mandatory Must be `2` for dynamic groups. #### groupType (string) — Mandatory Must be `1` (Computers). Dynamic custom groups only support computer-type — user-type dynamic groups are not supported. #### description (string) — Optional Group description. Max 250 chars. #### criteriaList (JSON array) — Mandatory Linear ordered array of filter criteria (1-based positional indices). Fetch available columns/operators from [Get Dynamic CG Criteria Pattern](https://www.manageengine.com/products/desktop-central/custom-groups-get-dynamic-cgcriteria-pattern.html). Each item is a JSON object with: ##### columnId (long) — Mandatory Criteria column ID. Fetch from [Get Dynamic CG Criteria Pattern](https://www.manageengine.com/products/desktop-central/custom-groups-get-dynamic-cgcriteria-pattern.html). Column IDs are instance-specific — never hardcode them, always discover via the criteriaPattern endpoint. ##### logicalOperator (string) — Mandatory How this criteria joins with the next: `'AND'` (both must match) or `'OR'` (either matches). ##### comparator (string) — Mandatory Comparison operator. Fetch applicable operators from [Get Dynamic CG Criteria Pattern](https://www.manageengine.com/products/desktop-central/custom-groups-get-dynamic-cgcriteria-pattern.html) via `applicableCriteriaType[].value`. Values: - `equal` - `not equal` - `contains` - `not contains` - `starts with` - `not starts with` - `ends with` - `greater than` - `greater or equal` - `less than` - `less or equal` - `between` - `not between` - `on` - `after` - `before` ##### criteriaValue (array) — Mandatory Array of string values to compare against. Multiple values act as OR within this criteria. Fetch available values from [Get Dynamic CG Column Values](https://www.manageengine.com/products/desktop-central/custom-groups-get-dynamic-cgcolumn-values.html). ##### additionalValues (JSON object) — Optional *Script-based criteria only* — Script execution parameters: exit code, script ID, name, and description. - **exitCode (string)** — Optional Comma-separated expected exit codes (e.g., `'0'` for success, `'0,1'` for success or warning). - **scriptId (string)** — Optional Resource ID of the custom script in the scripts repository. - **scriptName (string)** — Optional File name of the script (e.g., `'ComplianceCheck.bat'`). - **description (string)** — Optional Human-readable description of what the script checks. #### criteriaPattern (string) — Mandatory Combinator expression declaring how the entries of `criteriaList` are joined. Numbers are 1-based positional indices into the `criteriaList` array. Format examples: - `'1'` — single criterion - `'1 AND 2'` or `'1 OR 2'` — two criteria - `'(1 OR 2) AND 3'` — grouped/nested patterns The per-item `logicalOperator` field is **NOT** used to combine criteria — only `criteriaPattern` is. The server rejects requests where `criteriaPattern` is missing or empty with error code `70503` (`CG_NULL_CRITERIA_PATTERN`). --- ## Sample Request ### Curl ```bash curl --request POST \ --url https://appdomain/api/1.4/customgroup/addCg \ --header 'Accept: application/json' \ --header 'Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52' \ --header 'Content-Type: application/json' \ --data '{"groupName":"Windows 11 PCs","groupType":1,"groupCategory":2,"criteriaList":[{"comparator":"contains","logicalOperator":"AND","columnId":1,"criteriaValue":["Windows 11"]}],"criteriaPattern":"1"}' ``` ### Java ```java import java.net.URI; import java.net.http.HttpClient; import java.net.http.HttpRequest; import java.net.http.HttpResponse; import java.io.IOException; import java.net.http.HttpTimeoutException; public class Main { public static void main(String[] args) { HttpRequest request = HttpRequest.newBuilder() .uri(URI.create("https://appdomain/api/1.4/customgroup/addCg")) .header("Content-Type", "application/json") .header("Accept", "application/json") .header("Authorization", "Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52") .method("POST", HttpRequest.BodyPublishers.ofString("{\"groupName\":\"Windows 11 PCs\",\"groupType\":1,\"groupCategory\":2,\"criteriaList\":[{\"comparator\":\"contains\",\"logicalOperator\":\"AND\",\"columnId\":1,\"criteriaValue\":[\"Windows 11\"]}],\"criteriaPattern\":\"1\"}")) .build(); HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString()); System.out.println(response.body()); } } ``` ### Python ```python import http.client conn = http.client.HTTPSConnection("appdomain") payload = "{\"groupName\":\"Windows 11 PCs\",\"groupType\":1,\"groupCategory\":2,\"criteriaList\":[{\"comparator\":\"contains\",\"logicalOperator\":\"AND\",\"columnId\":1,\"criteriaValue\":[\"Windows 11\"]}],\"criteriaPattern\":\"1\"}" headers = { 'Content-Type': "application/json", 'Accept': "application/json", 'Authorization': "Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52" } conn.request("POST", "/api/1.4/customgroup/addCg", payload, headers) res = conn.getresponse() data = res.read() print(data.decode("utf-8")) ``` ### Deluge ```javascript headersMap = Map(); headersMap.put("Content-Type", "application/json"); headersMap.put("Accept", "application/json"); data=Map(); data.put("groupName","value"); data.put("groupType","value"); data.put("groupCategory","value"); data_criteriaList=List(); data_criteriaList_item1=Map(); data_criteriaList_item1.put("comparator","value"); data_criteriaList_item1.put("logicalOperator","value"); data_criteriaList_item1.put("columnId","1"); data_criteriaList_item1_criteriaValue=List(); data_criteriaList_item1.put("criteriaValue",data_criteriaList_item1_criteriaValue); data_criteriaList.add(data_criteriaList_item1); data.put("criteriaList",data_criteriaList); data.put("criteriaPattern","value"); response = invokeUrl [ url: "https://appDomain/api/1.4/customgroup/addCg" type: POST headers: headersMap body: data connection: connection_name ] info response; ``` ### PowerShell ```powershell $headers=@{} $headers.Add("Content-Type", "application/json") $headers.Add("Accept", "application/json") $headers.Add("Authorization", "Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52") $response = Invoke-WebRequest -Uri 'https://appdomain/api/1.4/customgroup/addCg' -Method POST -Headers $headers -ContentType 'application/json' -Body '{"groupName":"Windows 11 PCs","groupType":1,"groupCategory":2,"criteriaList":[{"comparator":"contains","logicalOperator":"AND","columnId":1,"criteriaValue":["Windows 11"]}],"criteriaPattern":"1"}' ``` --- ## Sample Request Body ### Dynamic group matching all computers with Windows 11 OS ```json { "groupName": "Windows 11 PCs", "groupType": 1, "groupCategory": 2, "description": "All computers running Windows 11", "criteriaList": [ { "comparator": "contains", "logicalOperator": "AND", "columnId": 1, "criteriaValue": [ "Windows 11" ] } ], "criteriaPattern": "1" } ``` ### Dynamic group with OS and architecture criteria (`criteriaPattern` = `1 AND 2`) ```json { "groupName": "Win11 x64 Workstations", "groupType": 1, "groupCategory": 2, "description": "Windows 11 64-bit workstations", "criteriaList": [ { "comparator": "contains", "logicalOperator": "AND", "columnId": 1, "criteriaValue": [ "Windows 11" ] }, { "comparator": "equal", "logicalOperator": "AND", "columnId": 3, "criteriaValue": [ "64-bit" ] } ], "criteriaPattern": "1 AND 2" } ``` ### Dynamic group using custom script exit code as criteria ```json { "groupName": "Compliant Machines", "groupType": 1, "groupCategory": 2, "description": "Machines passing compliance script", "criteriaList": [ { "comparator": "equal", "logicalOperator": "AND", "columnId": 22, "criteriaValue": [ "0" ], "additionalValues": { "scriptId": "5001", "exitCode": "0", "scriptName": "ComplianceCheck.bat", "description": "Verifies security compliance" } } ], "criteriaPattern": "1" } ``` --- ## Response Parameters ### HTTP 200 — Response Body (application/json) JSON object: #### message_type (string) Always `'addCg'` for this endpoint. #### message_response (JSON object) Response payload container. - **addcg (JSON object)** - **cgResourceId (string)** Newly assigned resource ID (returned as string). Use as `cgId` in [Delete CG](https://www.manageengine.com/products/desktop-central/custom-groups-delete-cg.html), or as `groupId` in the request body of [Update Dynamic CG](https://www.manageengine.com/products/desktop-central/custom-groups-update-dynamic-cg.html). - **groupName (string)** Name of the created group (echoed from request). - **groupCategory (string)** Always `'2'` (Dynamic) for this endpoint. - **groupType (string)** Group type as numeric string: `'1'` for Computers, `'2'` for Users. NOT the display name. #### message_version (string) API version: `'1.4'`. #### status (string) `'success'` when the request completed without errors. ### Sample Response — HTTP 200 ```json { "message_type": "addCg", "message_response": { "addcg": { "groupName": "Windows 11 PCs", "groupType": "1", "groupCategory": "2", "cgResourceId": "302" } }, "message_version": "1.4", "status": "success" } ``` --- ### HTTP 412 — Response Body (application/json) JSON object: - **message_type (string)** — Always `'addCg'` - **message_version (string)** — `'1.4'` - **status (string)** — Always `'error'` - **error_code (string)** - `'70501'` (CG_CREATE_UPDATE_PARAMS_MISSING) - `'70502'` (CG_DUPLICATE_NAME) - `'70504'` (CG_INVALID_GROUP_TYPE) - `'70505'` (CG_INVALID_GROUP_CATEGORY) - `'70503'` (CG_NULL_CRITERIA_PATTERN) - `'70517'` (CG_INVALID_CRITERIA_PATTERN) - `'70508'` (CG_MORE_COMPUTERS_DUMMY_CG) - `'70513'` (CG_INVALID_CREATION_MODE) - **error_description (string)** — Resolved I18N message varies by error code. ### Sample Response — HTTP 412 **Missing required parameters** ```json { "error_description": "Required parameters are missing to create/update Custom Group.", "message_type": "addCg", "error_code": "70501", "message_version": "1.4", "status": "error" } ``` **Missing or empty criteriaPattern** ```json { "error_description": "Given criteria pattern is null.", "message_type": "addCg", "error_code": "70503", "message_version": "1.4", "status": "error" } ``` --- ### HTTP 500 — Response Body (application/json) JSON object: - **message_type (string)** — Always `'addCg'` - **message_version (string)** — `'1.4'` - **status (string)** — Always `'error'` - **error_code (string)** — `'1003'` (INTERNAL_ERROR) - **error_description (string)** — Typically: *An internal error occurred while processing the request.* ### Sample Response — HTTP 500 ```json { "error_description": "An internal error occurred while processing the request.", "message_type": "addCg", "error_code": "1003", "message_version": "1.4", "status": "error" } ``` --- ## Possible Response Codes - **200** - **412** - **500** --- **Duration:** 1 minute **Threshold:** 30 **Lock period:** 5 minutes - **Duration** — Time window for the threshold. - **Threshold** — Number of API calls allowed within the specified duration. - **Lock Period** — Wait time before consecutive API requests.