# 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/help/api/cloud/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/help/api/cloud/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`.

## Endpoint

`POST /api/1.4/customgroup/addCg`

## Request URL

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

`{serverurl}`: [OAuth Authentication Endpoint Domain](https://www.manageengine.com/products/desktop-central/help/api/cloud/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/help/api/cloud/custom-groups-get-dynamic-cgcriteria-pattern.html).

- **criteriaPattern** `string` — **Mandatory**

  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
curl --request POST \
  --url https://appdomains/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"}'
```

## 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, combined using `criteriaPattern '1 AND 2'` (1-based indices into `criteriaList`).

```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 with `additionalValues`.

```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 Code 200

Response Body: `application/json`

JSON Object:

- **message_type** `string`

  Always `'addCg'` for this endpoint.

- **message_response** `JSON Object`

  Response payload container.

- **message_version** `string`

  API version: `'1.4'`.

- **status** `string`

  `'success'` when the request completed without errors.

### HTTP Code 412

Response Body: `application/json`

JSON Object:

- **message_type** `string`

  Always `'addCg'` for this endpoint.

- **message_version** `string`

  API version: `'1.4'`.

- **status** `string`

  Always `'error'` for error responses.

- **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: `'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:

- **message_type** `string`

  Always `'addCg'` for this endpoint.

- **message_version** `string`

  API version: `'1.4'`.

- **status** `string`

  Always `'error'` for error responses.

- **error_code** `string`

  Internal error code: `'1003'` (`INTERNAL_ERROR`).

- **error_description** `string`

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

## Possible Response Codes

- `200` — HTTP code
- `412` — HTTP code
- `500` — HTTP code

## Sample Response: HTTP 200

Dynamic group created with auto-populated membership.

```json
{
  "message_type": "addCg",
  "message_response": {
    "addcg": {
      "groupName": "Windows 11 PCs",
      "groupType": "1",
      "groupCategory": "2",
      "cgResourceId": "302"
    }
  },
  "message_version": "1.4",
  "status": "success"
}
```

## Sample Response: HTTP 412

`criteriaList` is required for dynamic groups but was not provided.

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

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

```json
{
  "error_description": "Given criteria pattern is null.",
  "message_type": "addCg",
  "error_code": "70503",
  "message_version": "1.4",
  "status": "error"
}
```

## Sample Response: HTTP 500

Unexpected server-side failure during group creation.

```json
{
  "error_description": "An internal error occurred while processing the request.",
  "message_type": "addCg",
  "error_code": "1003",
  "message_version": "1.4",
  "status": "error"
}
```

## Rate Limit

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