Creates a dynamic custom group with criteria-based membership

Open in ChatGPT Open in ChatGPT to ask questions about this page
Open in Claude Open in Claude to ask questions about this page
Copy as MarkdownCopy this page as markdown to use with AI assistants
View as Markdown Open this page as markdown in a new tab

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 to discover available columns and operators. (2) Call Get Dynamic CG Column Values 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

Request URL

https://{serverurl}/api/1.4/customgroup/addCg

Scope

DesktopCentralCloud.Common.UPDATECopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

Content-TypestringMandatory
application/jsonapplication/jsonCopied!

Must be application/json. Request body must be valid JSON.

AcceptstringMandatory
application/jsonapplication/jsonCopied!

Must be application/json. Only JSON responses are supported.

- Request Body

application/json
JSON object
Hide Sub-Attributes
groupNamestringMandatory

Name for the new group. Must be unique. Max 100 chars.

Forbidden characters: ` \ : ; < > ? * " | & # % /

groupCategorystringMandatory

Must be 2 for dynamic groups.

groupTypestringMandatory

Must be 1 (Computers). Dynamic custom groups only support computer-type — user-type dynamic groups are not supported.

descriptionstringOptional

Group description. Max 250 chars.

criteriaListJSON arrayMandatory

Linear ordered array of filter criteria (1-based positional indices). Fetch available columns/operators from Get Dynamic CG Criteria Pattern.

Show Sub-Attributes
JSON object
Show Sub-Attributes
columnIdlongMandatory

Criteria column ID. Fetch from Get Dynamic CG Criteria Pattern. Column IDs are instance-specific — never hardcode them, always discover via the criteriaPattern endpoint.

logicalOperatorstringMandatory

How this criteria joins with the next: 'AND' (both must match) or 'OR' (either matches).

comparatorstringMandatory

Comparison operator. Fetch applicable operators from Get Dynamic CG Criteria Pattern 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'.

criteriaValuearrayMandatory

Array of string values to compare against. Multiple values act as OR within this criteria. Fetch available values from Get Dynamic CG Column Values.

additionalValuesJSON objectOptional

[Script-based criteria only] Script execution parameters: exit code, script ID, name, and description.

Show Sub-Attributes
exitCodestringOptional

Comma-separated expected exit codes (e.g., '0' for success, '0,1' for success or warning).

scriptIdstringOptional

Resource ID of the custom script in the scripts repository.

scriptNamestringOptional

File name of the script (e.g., 'ComplianceCheck.bat').

descriptionstringOptional

Human-readable description of what the script checks.

criteriaPatternstringMandatory

Combinator expression declaring how the entries of criteriaList are joined. Numbers are 1-based positional indices into the criteriaList array. Format: '1' for a single criterion, '1 AND 2' / '1 OR 2' for two criteria, '(1 OR 2) AND 3' for 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
Java
Python
Deluge
PowerShell
Copied!
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"}'
Show full

Sample Request Body

Dynamic group matching all computers with Windows 11 OS.

Copied!
  {
    "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"
  }
                
Show full

Dynamic group with OS and architecture criteria, combined using criteriaPattern '1 AND 2' (1-based indices into criteriaList).

Copied!
  {
    "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"
  }
                
Show full

Dynamic group using custom script exit code as criteria with additionalValues.

Copied!
  {
    "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"
  }
                
Show full

Response Parameters

- HTTP code 200

Response Body - application/json


JSON object
Hide Sub-Attributes
message_typestring

Always 'addCg' for this endpoint.

message_responseJSON object

Response payload container.

Show Sub-Attributes
addcgJSON object

Response payload.

Show Sub-Attributes
cgResourceIdstring

Newly assigned resource ID (returned as string). Use as cgId in Delete CG, or as groupId in the request body of Update Dynamic CG.

groupNamestring

Name of the created group (echoed from request).

groupCategorystring

Always '2' (Dynamic) for this endpoint.

groupTypestring

Group type as numeric string: '1' for Computers, '2' for Users. NOT the display name.

message_versionstring

API version: '1.4'.

statusstring

'success' when the request completed without errors.

- HTTP code 412

Response Body - application/json


JSON object
Hide Sub-Attributes
message_typestring

Always 'addCg' for this endpoint.

message_versionstring

API version: '1.4'.

statusstring

Always 'error' for error responses.

error_codestring

'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_descriptionstring

Resolved I18N message varies by error code: 'Required parameters are missing to create/update Custom Group.' (70501), 'Custom group name is already in use.' (70502), 'Invalid group type.' (70504), 'Invalid group category.' (70505), 'Criteria pattern is empty.' (70503), 'Invalid criteria pattern.' (70517), 'Computer limit exceeded for free edition.' (70508), 'Only manually created Custom Group is allowed to be accessed using external apis.' (70513).

- HTTP code 500

Response Body - application/json


JSON object
Hide Sub-Attributes
message_typestring

Always 'addCg' for this endpoint.

message_versionstring

API version: '1.4'.

statusstring

Always 'error' for error responses.

error_codestring

Internal error code: '1003' (INTERNAL_ERROR).

error_descriptionstring

Resolved I18N message, typically: An internal error occurred while processing the request.

Possible Response Codes

200HTTP code
412HTTP code
500HTTP code

Sample Response: HTTP 200

Dynamic group created with auto-populated membership.

Copied!
  {
    "message_type": "addCg",
    "message_response": {
      "addcg": {
        "groupName": "Windows 11 PCs",
        "groupType": "1",
        "groupCategory": "2",
        "cgResourceId": "302"
      }
    },
    "message_version": "1.4",
    "status": "success"
  }
                
Show full

Sample Response: HTTP 412

criteriaList is required for dynamic groups but was not provided.

Copied!
  {
    "error_description": "Required parameters are missing to create/update Custom Group.",
    "message_type": "addCg",
    "error_code": "70501",
    "message_version": "1.4",
    "status": "error"
  }
                
Show full

criteriaPattern is required for dynamic groups but was omitted or empty.

Copied!
  {
    "error_description": "Given criteria pattern is null.",
    "message_type": "addCg",
    "error_code": "70503",
    "message_version": "1.4",
    "status": "error"
  }
                
Show full

Sample Response: HTTP 500

Unexpected server-side failure during group creation.

Copied!
  {
    "error_description": "An internal error occurred while processing the request.",
    "message_type": "addCg",
    "error_code": "1003",
    "message_version": "1.4",
    "status": "error"
  }
                
Show full

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.