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

## Endpoint

`GET /api/1.4/customgroup/ouTree`

## Request

### Request URL

https://[{serverurl}](https://www.manageengine.com/products/desktop-central/help/api/cloud/oauth-authentication-endpoint-domain.html)/api/1.4/customgroup/ouTree

### Scope

`DesktopCentralCloud.Common.READ`

### Header

`Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52`

### Request Parameters

#### Request Headers

- **Accept** `string` — **Mandatory**
  - `application/json`
  - Must be application/json. Only JSON responses are supported.

#### Query Parameters

- **groupCategory** `string` — Optional
  - 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.
- **groupType** `string` — Optional
  - 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.
- **domainName** `string` — Optional
  - 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.
- **guid** `string` — Optional
  - 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.
- **adLevel** `string` — Optional
  - 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.
- **isAdDomain** `boolean` — Optional
  - 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
curl --request GET \
  --url https://appdomains/api/1.4/customgroup/ouTree \
  --header 'Accept: application/json' \
  --header 'Authorization: Zoho-oauthtoken  d92d4xxxxxxxxxxxxx15f52'
```

## Response Parameters

### HTTP Code 200

Response body: `application/json`

- `JSON Object`
  - **message_type** `string`
    - Always `'ouTree'` 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 500

Response body: `application/json`

- `JSON Object`
  - **message_type** `string`
    - Always `'ouTree'` 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
- **500** — HTTP code

## Sample Responses

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

```json
{
  "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"
}
```

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

```json
{
  "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"
}
```

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

```json
{
  "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"
}
```

### HTTP 500

Unexpected server-side failure retrieving OU tree.

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