Retrieves the Active Directory OU/group tree for browsing

Returns the hierarchical tree of Active Directory organizational units (OUs), computers, and users for the specified domain. The initial call (no guid) returns domain-level nodes. Expanding a node (with guid) returns child OUs and computer/user leaf members. Used for browsing managed AD domain structure. Supports filtering by domain, GUID, AD level, and group type/category.

Endpoints

get /api/1.4/customgroup/ouTree

Copy full URL

Request URL

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

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

groupCategorystringOptional

Group category context for computer filtering when expanding an AD OU: 1=Static, 2=Dynamic, 5=Static Unique. Used to filter unmanaged computers; does not change category-level visibility of OUs. Ignored for the root-domain list.

groupTypestringOptional

Branch the leaf-node query when expanding an AD OU: 1=Computers (returns computers under the OU), any other value (e.g., 2=Users) returns AD users. Ignored for the root-level domain list.

domainNamestringOptional

NetBIOS name of the AD domain (or workgroup) to expand. Omit (along with guid) to retrieve the root-level managed-domain list. When provided, guid must also be provided to expand a specific node.

guidstringOptional

GUID of the AD OU/container/domain to expand. Omit (or omit domainName) to get the root list of managed domains. Required together with domainName for any node expansion. For AD root expansion, pass the domain GUID.

adLevelstringOptional

AD hierarchy depth. Pass 'all' (or any string starting with 'all') to retrieve the entire subtree under the given guid. Any other value (or omitted) returns only immediate children. Default: immediate children only.

isAdDomainbooleanOptional

Whether the specified domain is an AD domain (true) or a workgroup (false). Used when expanding a specific node (both domainName and guid must be supplied together). Default: false. For workgroup expansion, child expansion lists managed resources directly.

Sample Request

Curl

Java

Python

Deluge

PowerShell

Copied!

curl --request GET \
  --url https://appdomains/api/1.4/customgroup/ouTree \
  --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://appdomains/api/1.4/customgroup/ouTree"))
        .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("appdomains")

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

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

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

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


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

    response = invokeUrl
    [
        url: "https://appDomains/api/1.4/customgroup/ouTree"
        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://appdomains/api/1.4/customgroup/ouTree' -Method GET -Headers $headers

Response Parameters

- HTTP code 200

Response Body - application/json

JSON Object

Hide Sub-Attributes

message_typestring

Always 'ouTree' for this endpoint.

message_responseJSON Object

Response payload container.

Show Sub-Attributes

outreeJSON Object

Response payload.

Show Sub-Attributes

targetsJSON Array

Flat list of tree nodes with id/parent hierarchy. Parent references build the tree client-side.

Show Sub-Attributes

JSON Object

Show Sub-Attributes

idstring

Unique identifier for this node in the tree (typically the GUID or a synthetic ID).

parentstring

ID of the parent node. '--' for root-level domain/workgroup nodes; parent GUID for child OU/computer/user nodes.

labelstring

Display name of the AD object: domain NetBIOS name or OU name.

domainNamestring

NetBIOS domain this object belongs to.

targetTypestring

Node type as numeric string: '5'=Domain, '6'=OU, '1'=Computer (leaf), '2'=User (leaf).

guidstring

Active Directory GUID for this node. '--' for workgroup nodes.

distinguishedNamestring

Full LDAP distinguished name (e.g., 'OU=Finance,DC=corp,DC=local'). Present for AD domain nodes (auto-derived from AD domain name) and OU nodes. Absent for workgroup and computer/user leaf nodes.

isAdDomainboolean

[Domain-level nodes only] Whether this domain is an Active Directory domain (true) or a workgroup (false). Not present on child OU/computer/user nodes.

osPlatformstring

[Computer leaf nodes only] OS platform identifier (e.g., 1=Windows, 2=Mac, 3=Linux). Present only when targetType is Computer.

propertiesJSON Object

UI state properties for the tree node.

Show Sub-Attributes

isSelectedboolean

Whether this node is pre-selected in the tree UI.

selectableboolean

Whether this node can be selected.

expandableboolean

Whether this node has children that can be expanded.

message_versionstring

API version: '1.4'.

statusstring

'success' when the request completed without errors.

- HTTP code 500

Response Body - application/json

JSON Object

Hide Sub-Attributes

message_typestring

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

500HTTP code

Sample Response: HTTP 200

Root call to /ouTree (no domainName, no guid) returns the managed-domain list. AD domains have targetType=5 with isAdDomain=true and a synthesised distinguishedName. Child OUs/computers/users are fetched in a follow-up call with that domain's guid; this example interleaves them for illustration. targetType uses Resource constants: 5=Domain, 6=OU/Container, 1=Computer (leaf), 2=User (leaf). Root parent is '--'.

Copied!

  {
    "message_type": "ouTree",
    "message_response": {
      "outree": {
        "targets": [
          {
            "isAdDomain": true,
            "parent": "--",
            "domainName": "CORP",
            "guid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "distinguishedName": "DC=corp,DC=local",
            "targetType": "5",
            "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "label": "CORP",
            "properties": {
              "expandable": true,
              "selectable": false,
              "isSelected": false
            }
          },
          {
            "parent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "domainName": "CORP",
            "guid": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "distinguishedName": "OU=Finance,DC=corp,DC=local",
            "targetType": "6",
            "id": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "label": "Finance",
            "properties": {
              "expandable": true,
              "selectable": true,
              "isSelected": false
            }
          },
          {
            "parent": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
            "domainName": "CORP",
            "guid": "d4e5f6a7-b8c9-0123-defa-234567890123",
            "distinguishedName": "OU=Engineering,DC=corp,DC=local",
            "targetType": "6",
            "id": "d4e5f6a7-b8c9-0123-defa-234567890123",
            "label": "Engineering",
            "properties": {
              "expandable": false,
              "selectable": true,
              "isSelected": false
            }
          }
        ]
      }
    },
    "message_version": "1.4",
    "status": "success"
  }

▼ Show full

Workgroup domain tree (isAdDomain=false) with no OU hierarchy. Workgroup nodes lack distinguishedName.

Copied!

  {
    "message_type": "ouTree",
    "message_response": {
      "outree": {
        "targets": [
          {
            "isAdDomain": false,
            "parent": "--",
            "domainName": "WORKGROUP",
            "guid": "",
            "targetType": "5",
            "id": "12345",
            "label": "WORKGROUP",
            "properties": {
              "expandable": true,
              "selectable": true,
              "isSelected": false
            }
          }
        ]
      }
    },
    "message_version": "1.4",
    "status": "success"
  }

▼ Show full

Expanding a specific OU by guid parameter to load its child OUs.

Copied!

  {
    "message_type": "ouTree",
    "message_response": {
      "outree": {
        "targets": [
          {
            "parent": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "domainName": "CORP",
            "guid": "c3d4e5f6-a7b8-9012-cdef-123456789012",
            "distinguishedName": "OU=Finance-Workstations,OU=Finance,DC=corp,DC=local",
            "targetType": "6",
            "id": "c3d4e5f6-a7b8-9012-cdef-123456789012",
            "label": "Finance-Workstations",
            "properties": {
              "expandable": false,
              "selectable": true,
              "isSelected": false
            }
          },
          {
            "parent": "b2c3d4e5-f6a7-8901-bcde-f12345678901",
            "domainName": "CORP",
            "guid": "f7a8b9c0-d1e2-3456-abcd-678901234567",
            "distinguishedName": "OU=Accounting,OU=Finance,DC=corp,DC=local",
            "targetType": "6",
            "id": "f7a8b9c0-d1e2-3456-abcd-678901234567",
            "label": "Accounting",
            "properties": {
              "expandable": false,
              "selectable": true,
              "isSelected": false
            }
          }
        ]
      }
    },
    "message_version": "1.4",
    "status": "success"
  }

▼ Show full

Sample Response: HTTP 500

Unexpected server-side failure retrieving OU tree.

Copied!

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