# 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/onpremise/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/onpremise/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

### Request URL

`https://{server-hostname}:8383/api/1.4/customgroup/addCg`

### Scope

`Common.UPDATE`

### Header

`Authorization: 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`

- **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/onpremise/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://appdomain/api/1.4/customgroup/addCg \
  --header 'Accept: application/json' \
  --header 'Authorization:  d92d4xxxxxxxxxxxxx15f52' \
  --header 'Content-Type: application/json' \
  --data '{"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"}'
```

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

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

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

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

![Help icon](https://www.zohowebstatic.com/sites/zweb/images/people/ico-help.png)

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