Creates a static unique custom group with exclusive resource 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 static unique custom group (groupCategory=5) with explicit member resources. Only computer-type static unique groups are supported — user-type static unique groups are not allowed. Static Unique groups are used for Scope of Management — they enforce that each resource belongs to only ONE static unique group of the same type, enabling non-overlapping technician territories. Unlike regular Static groups where a resource can belong to multiple groups, Static Unique groups reject any resource already in another Static Unique group. Required: groupName, groupType=1, groupCategory=5, resourceIds. Prerequisites: Call Get Available Resources to discover valid resource IDs.

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 5 for static unique groups.

groupTypestringMandatory

Must be 1 (Computers). Static unique custom groups only support computer-type — user-type static unique groups are not supported.

descriptionstringOptional

Group description. Max 250 chars. Double quotes not allowed.

resourceIdsarrayMandatory

Array of resource IDs. Members must be exclusive — each resource can only belong to ONE static unique group of the same type. Resources already in another static unique group will be reported in invalidResourceIds. Fetch IDs from Get Available Resources.

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":"Privileged Servers","groupType":1,"groupCategory":5,"resourceIds":[101,102]}'
Show full

Sample Request Body

Create a static unique computer group with exclusive members.

Copied!
  {
    "groupName": "Privileged Servers",
    "groupType": 1,
    "groupCategory": 5,
    "description": "Servers with restricted technician access",
    "resourceIds": [
      101,
      102
    ]
  }
                
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 Static CG or Update Static Unique CG.

groupNamestring

Name of the created group (echoed from request).

groupCategorystring

Numeric category as string: '1'=Static, '5'=Static Unique.

groupTypestring

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

invalidResourceIdsarray

[Conditional] Array of resource IDs that were not found or not valid. Present only when some submitted resourceIds are invalid.

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

Static unique group created with assigned resource ID.

Copied!
  {
    "message_type": "addCg",
    "message_response": {
      "addcg": {
        "groupName": "Privileged Servers",
        "groupType": "1",
        "groupCategory": "5",
        "cgResourceId": "310"
      }
    },
    "message_version": "1.4",
    "status": "success"
  }
                
Show full

Static unique group created but some exclusive member resource IDs were not found.

Copied!
  {
    "message_type": "addCg",
    "message_response": {
      "addcg": {
        "groupName": "Privileged Servers",
        "groupType": "1",
        "groupCategory": "5",
        "invalidResourceIds": [
          999,
          998
        ],
        "cgResourceId": "310"
      }
    },
    "message_version": "1.4",
    "status": "success"
  }
                
Show full

Sample Response: HTTP 412

A group with this name already exists.

Copied!
  {
    "error_description": "Custom group name is already in use.",
    "message_type": "addCg",
    "error_code": "70502",
    "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.