Retrieves the list of all custom groups

Returns details of all custom groups including group ID, name, type (Computers/Users), category (Static/Dynamic/Static Unique), associated domain, and creation/modification timestamps. By default, auto-generated system groups (All Computers, All Users) are excluded. The returned groupId values can be passed as cgId to Delete CG or as groupId in the request body of Update Static CG, Update Static Unique CG, or Update Dynamic CG. The returned groupName values can be used with Retrieve Custom Group Details.

Endpoints

get /api/1.4/customgroup/getCGList

Copy full URL

Request URL

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

Scope

DesktopCentralCloud.Common.READCopied!

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Request Parameters

- Request Headers

AcceptstringMandatory

application/jsonCopied!

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

- Query Parameters

isAutoGeneratedCGNeededbooleanOptional

Include auto-generated system groups (e.g., All Computers, All Users) in the response. Default: false

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request GET \
  --url https://appdomain/api/1.4/customgroup/getCGList \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52'

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/getCGList"))
        .header("Accept", "application/json")
        .header("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
        .method("GET", HttpRequest.BodyPublishers.noBody())
        .build();
    HttpResponse response = HttpClient.newHttpClient().send(request, HttpResponse.BodyHandlers.ofString());
    System.out.println(response.body());
  
  }
}

import http.client

conn = http.client.HTTPSConnection("appdomain")

headers = {
    'Accept': "application/json",
    'Authorization': "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52"
    }

conn.request("GET", "/api/1.4/customgroup/getCGList", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))


    headersMap = Map();
    headersMap.put("Accept", "application/json");

    response = invokeUrl
    [
        url: "https://appDomain/api/1.4/customgroup/getCGList"
        type: GET
        headers: headersMap
        
        
        connection: connection_name
    ]

    info response;

$headers=@{}
$headers.Add("Accept", "application/json")
$headers.Add("Authorization", "Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52")
$response = Invoke-WebRequest -Uri 'https://appdomain/api/1.4/customgroup/getCGList' -Method GET -Headers $headers

▼ Show full

Response Parameters

- HTTP code 200

Response Body - application/json

JSON object

Hide Sub-Attributes

message_typestring

Always 'getCGList' for this endpoint.

message_responseJSON object

Response payload container.

Show Sub-Attributes

getcglistJSON object

Response payload.

Show Sub-Attributes

operation_statusstring

Operation result: 'success' when the request completed without errors.

responseJSON object

Wrapper containing the success message and result payload.

Show Sub-Attributes

messagestring

Fixed success string: 'Operation has been completed successfully'.

resultJSON object

Result payload containing the cg_list array.

Show Sub-Attributes

cg_listJSON array

Array of custom group summaries without member details.

Show Sub-Attributes

JSON object

Show Sub-Attributes

group_idlong

Unique resource ID of the custom group. Use as cgId in Delete CG, as groupId in the request body of Update Static CG / Update Static Unique CG / Update Dynamic CG, or as sourceCGId in Clone Dynamic CG.

group_namestring

Display name of the custom group (must be unique).

group_typestring

Human-readable type: 'Computers' (groupType=1) or 'Users' (groupType=2).

group_categorystring

Human-readable category: 'Static' (1), 'Dynamic' (2), 'Static Unique' (5), or 'All Computer/User Group' (10).

domain_namestring

NetBIOS domain name. 'NA' for dynamic groups which are not domain-specific.

group_created_onlong

Timestamp (ms since epoch) when the group was first created.

group_modified_onlong

Timestamp (ms since epoch) of the last modification to the group or its members.

message_versionstring

API version: '1.4'.

statusstring

'success' when the request completed without errors.

- HTTP code 204

Response Body - application/json

JSON object

Hide Sub-Attributes

message_typestring

Always 'getCGList' for this endpoint.

message_versionstring

API version: '1.4'.

statusstring

Always 'error' for error responses.

error_codestring

Internal error code: '20012' (no custom groups found).

error_descriptionstring

Human-readable error message.

- HTTP code 417

Response Body - application/json

JSON object

Hide Sub-Attributes

message_typestring

Always 'getCGList' for this endpoint.

message_versionstring

API version: '1.4'.

statusstring

Always 'error' for error responses.

error_codestring

Internal error code: '20003' (no managed domains).

error_descriptionstring

Human-readable error message.

- HTTP code 500

Response Body - application/json

JSON object

Hide Sub-Attributes

message_typestring

Always 'getCGList' 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

204HTTP code

417HTTP code

500HTTP code

Sample Response: HTTP 200

List with static, dynamic, static unique computer and user groups.

Copied!

  {
    "message_type": "getCGList",
    "message_response": {
      "getcglist": {
        "response": {
          "result": {
            "cg_list": [
              {
                "domain_name": "CORP",
                "group_category": "Static",
                "group_id": 301,
                "group_name": "Windows Servers",
                "group_modified_on": 1710412000000,
                "group_created_on": 1710325600000,
                "group_type": "Computers"
              },
              {
                "domain_name": "NA",
                "group_category": "Dynamic",
                "group_id": 302,
                "group_name": "Windows 11 PCs",
                "group_modified_on": 1710500000000,
                "group_created_on": 1710325600000,
                "group_type": "Computers"
              },
              {
                "domain_name": "CORP",
                "group_category": "Static Unique",
                "group_id": 303,
                "group_name": "Finance OU Computers",
                "group_modified_on": 1710500000000,
                "group_created_on": 1710240000000,
                "group_type": "Computers"
              },
              {
                "domain_name": "CORP",
                "group_category": "Static",
                "group_id": 304,
                "group_name": "HR Users",
                "group_modified_on": 1710150000000,
                "group_created_on": 1710150000000,
                "group_type": "Users"
              }
            ]
          },
          "message": "Operation has been completed successfully"
        },
        "operation_status": "success"
      }
    },
    "message_version": "1.4",
    "status": "success"
  }

▼ Show full

List including auto-generated All Computers group when isAutoGeneratedCGNeeded=true.

Copied!

  {
    "message_type": "getCGList",
    "message_response": {
      "getcglist": {
        "response": {
          "result": {
            "cg_list": [
              {
                "domain_name": "NA",
                "group_category": "All Computer/User Group",
                "group_id": 1,
                "group_name": "All Computers",
                "group_modified_on": 1710500000000,
                "group_created_on": 1700000000000,
                "group_type": "Computers"
              },
              {
                "domain_name": "CORP",
                "group_category": "Static",
                "group_id": 301,
                "group_name": "Windows Servers",
                "group_modified_on": 1710412000000,
                "group_created_on": 1710325600000,
                "group_type": "Computers"
              }
            ]
          },
          "message": "Operation has been completed successfully"
        },
        "operation_status": "success"
      }
    },
    "message_version": "1.4",
    "status": "success"
  }

▼ Show full

Sample Response: HTTP 204

No manually created custom groups exist in the system.

Copied!

  {
    "error_description": "No custom groups found",
    "message_type": "getCGList",
    "error_code": "20012",
    "message_version": "1.4",
    "status": "error"
  }

▼ Show full

Sample Response: HTTP 417

Server has no managed AD/workgroup domains configured.

Copied!

  {
    "error_description": "No managed domain(s) available",
    "message_type": "getCGList",
    "error_code": "20003",
    "message_version": "1.4",
    "status": "error"
  }

▼ Show full

Sample Response: HTTP 500

Unexpected server-side failure retrieving custom group list.

Copied!

  {
    "error_description": "An internal error occurred while processing the request.",
    "message_type": "getCGList",
    "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.