Organizational Units API

The Organizational Units (OUs) API provides programmatic access to manage Active Directory (AD) OUs. The ADManager Plus API offers endpoints to update and retrieve OUs using structured requests with support for filtering, sorting, and pagination. OUs are used to organize users, groups, computers, and other OUs within a domain, and the API enables administrators to automate restructuring, attribute updates, and reporting with consistency across environments.

Download Organizational Units API OpenAPI Document

End Points

GET

/organizational_units

PATCH

/organizational_units

List AD OUs

This endpoint retrieves AD OUs based on specified filters, sort order, and pagination. You can also limit the response to specific fields for efficiency. It is often used for OU inventory, reporting, or preparing for administrative delegation.

Scope : Read OU action, All OU management actions
Delegated role : All OUs Report

Query Parameters

from

integer

The starting index for pagination. Enables pagination through large result sets.

limit

integer

The maximum number of OU records to return per request.

domains

string

(Required)

A comma-separated list of domains from which to fetch OUs.
Example: domain1.com,domain2.com

fields

string

The attributes to be returned in the response.

filter

string

A SCIM filter query to refine which objects are returned. See Filter section for details.
eg: (FULL_NAME eq Finance) and (CITY eq New York)

sort

string

This field is used to sort results. The default sort order is ascending. To sort in descending order, prefix the field with a hyphen (-).
eg: FULL_NAME

refresh

boolean

If set to true, triggers a sync before fetching results, ensuring that the data reflects the latest state of AD.

Headers

string

The response format that the client accepts.

X-Module

string

The module name to be recorded in the audit logs. If not provided, the default module is recorded as Rest API.

X-Date-Time-Format

string

The date-time format to be used for parsing date values returned in the response. If not provided, the default ISO format is used (yyyy-MM-dd'T'HH:mm:ss[.SSS][XXX]).

Request Example

headers_data = Map();
headers_data.put("Accept", "application/json");
headers_data.put("X-Module", "External API");
headers_data.put("X-Date-Time-Format", "SOME_STRING_VALUE");
headers_data.put("Authorization", "REPLACE_KEY_VALUE");
response = invokeUrl
[
url: "http://admanagerplus:8080/api/v2/organizational_units?domains=domain1.com"
type: GET
headers: headers_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("http://admanagerplus:8080/api/v2/organizational_units?domains=domain1.com")
  .get()
  .addHeader("Accept", "application/json")
  .addHeader("X-Module", "External API")
  .addHeader("X-Date-Time-Format", "SOME_STRING_VALUE")
  .addHeader("Authorization", "REPLACE_KEY_VALUE")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Accept: 'application/json',
    'X-Module': 'External API',
    'X-Date-Time-Format': 'SOME_STRING_VALUE',
    Authorization: 'REPLACE_KEY_VALUE'
  }
};

fetch('http://admanagerplus:8080/api/v2/organizational_units?domains=domain1.com', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPConnection("admanagerplus:8080")

headers = {
    'Accept': "application/json",
    'X-Module': "External API",
    'X-Date-Time-Format': "SOME_STRING_VALUE",
    'Authorization': "REPLACE_KEY_VALUE"
    }

conn.request("GET", "/api/v2/organizational_units?domains=domain1.com", headers=headers)

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

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

const http = require("http");

const options = {
  "method": "GET",
  "hostname": "admanagerplus",
  "port": "8080",
  "path": "/api/v2/organizational_units?domains=domain1.com",
  "headers": {
    "Accept": "application/json",
    "X-Module": "External API",
    "X-Date-Time-Format": "SOME_STRING_VALUE",
    "Authorization": "REPLACE_KEY_VALUE"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'http://admanagerplus:8080/api/v2/organizational_units?domains=domain1.com' \
  --header 'Accept: application/json' \
  --header 'Authorization: REPLACE_KEY_VALUE' \
  --header 'X-Date-Time-Format: SOME_STRING_VALUE' \
  --header 'X-Module: External API'

Response Example

{
    "data": [
        {
            "NAME": "OUAPI1",
            "DISTINGUISHED_NAME": "OU=OUAPI1,OU=OUS,DC=domain,DC=com",
            "OU_NAME": "domain.com/OUS/OUAPI1",
            "CITY": "Chennai",
            "COUNTRY": "India",
            "STATE_PROVINCE": "-",
            "OBJECT_GUID": "{715EC375-CC40-9A61-9C8E-DF9B7989D3FD}",
            "MANAGER": "Manager 1"
        },
        {
            "NAME": "OUAPI2",
            "DISTINGUISHED_NAME": "OU=OUAPI2,OU=OUS,DC=domain,DC=com",
            "OU_NAME": "domain.com/OUS/OUAPI2",
            "CITY": "Bangalore",
            "COUNTRY": "India",
            "STATE_PROVINCE": "-",
            "OBJECT_GUID": "{715EC375-CC40-9A61-9C8E-DF9B7989D3FE}",
            "MANAGER": "Manager 2"
        }
    ],
    "meta": {
        "start_index": 1,
        "limit": 10,
        "total_no_of_objects": 2
    }
}

{
    "code": "00000100",
    "detail": "Some columns given in fields parameter are invalid",
    "title": "Bad Request."
}

{
    "code": "00000101",
    "detail": "The given Authtoken is invalid.",
    "title": "Unauthorized."
}

{
    "code": "00000000",
    "detail": "An internal server error occurred.",
    "title": "Internal Server Error."
}

Update AD OUs

This endpoint updates existing OUs with the specified payload. You can modify attributes such as name, description, location, and administrative details. It is commonly used when restructuring domains, changing OU ownership, or updating organizational information.

Scope : Modify OU action, All OU management actions
Delegated role : Modify Bulk OUs, Bulk OU Modification

Arguments

data

object

Data to be updated for the OU.

Show Sub-Attributes

attributes

object

The attributes of the OU to be updated.

Show Sub-Attributes

name

string

Name of the OU.

description

string

Description of the OU.

OUName

string

The container path where the OU should reside.

managedBy

string

Manager of the OU.

street

string

Street address of the OU.

state

string

State or province of the OU.

string

City of the OU.

postalCode

string

Postal code of the OU.

country

string

Country of the OU.

string

Two-letter country code of the OU.

preventDeletion

boolean

Specifies whether the OU is protected from deletion.

Query Parameters

from

integer

The starting index for pagination. Enables pagination through large result sets.

limit

integer

The maximum number of OU records to return per request.

domain

string

(Required)

The AD domain where the requested operation is performed.
eg: domain1.com

filter

string

A SCIM filter query to refine which objects are returned. See Filter section for details.
eg: (FULL_NAME eq Finance) and (CITY eq New York)

sort

string

This field is used to sort results. The default sort order is ascending. To sort in descending order, prefix the field with a hyphen (-).
eg: FULL_NAME

refresh

boolean

If set to true, triggers a sync before fetching results, ensuring that the data reflects the latest state of AD.

Headers

string

The response format that the client accepts.

X-Module

string

The module name to be recorded in the audit logs. If not provided, the default module is recorded as Rest API.

Request Example

parameters_data='{"data":{"attributes":{"name":"APIOU1","OUName":"OU=OUS,DC=domain,DC=com","managedBy":"Manager1","co":"India","extensionAttribute1":"Custom Value 1"}}}';
headers_data = Map();
headers_data.put("Accept", "application/json");
headers_data.put("X-Module", "External API");
headers_data.put("Authorization", "REPLACE_KEY_VALUE");
response = invokeUrl
[
url: "http://admanagerplus:8080/api/v2/organizational_units?domain=domain1.com"
type: PATCH
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
];
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"data\":{\"attributes\":{\"name\":\"APIOU1\",\"OUName\":\"OU=OUS,DC=domain,DC=com\",\"managedBy\":\"Manager1\",\"co\":\"India\",\"extensionAttribute1\":\"Custom Value 1\"}}}");
Request request = new Request.Builder()
  .url("http://admanagerplus:8080/api/v2/organizational_units?domain=domain1.com")
  .patch(body)
  .addHeader("Accept", "application/json")
  .addHeader("X-Module", "External API")
  .addHeader("Authorization", "REPLACE_KEY_VALUE")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'PATCH',
  headers: {
    Accept: 'application/json',
    'X-Module': 'External API',
    Authorization: 'REPLACE_KEY_VALUE',
    'content-type': 'application/json'
  },
  body: '{"data":{"attributes":{"name":"APIOU1","OUName":"OU=OUS,DC=domain,DC=com","managedBy":"Manager1","co":"India","extensionAttribute1":"Custom Value 1"}}}'
};

fetch('http://admanagerplus:8080/api/v2/organizational_units?domain=domain1.com', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPConnection("admanagerplus:8080")

payload = "{\"data\":{\"attributes\":{\"name\":\"APIOU1\",\"OUName\":\"OU=OUS,DC=domain,DC=com\",\"managedBy\":\"Manager1\",\"co\":\"India\",\"extensionAttribute1\":\"Custom Value 1\"}}}"

headers = {
    'Accept': "application/json",
    'X-Module': "External API",
    'Authorization': "REPLACE_KEY_VALUE",
    'content-type': "application/json"
    }

conn.request("PATCH", "/api/v2/organizational_units?domain=domain1.com", payload, headers)

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

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

const http = require("http");

const options = {
  "method": "PATCH",
  "hostname": "admanagerplus",
  "port": "8080",
  "path": "/api/v2/organizational_units?domain=domain1.com",
  "headers": {
    "Accept": "application/json",
    "X-Module": "External API",
    "Authorization": "REPLACE_KEY_VALUE",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({
  data: {
    attributes: {
      name: 'APIOU1',
      OUName: 'OU=OUS,DC=domain,DC=com',
      managedBy: 'Manager1',
      co: 'India',
      extensionAttribute1: 'Custom Value 1'
    }
  }
}));
req.end();

curl --request PATCH \
  --url 'http://admanagerplus:8080/api/v2/organizational_units?domain=domain1.com' \
  --header 'Accept: application/json' \
  --header 'Authorization: REPLACE_KEY_VALUE' \
  --header 'X-Module: External API' \
  --header 'content-type: application/json' \
  --data '{"data":{"attributes":{"name":"APIOU1","OUName":"OU=OUS,DC=domain,DC=com","managedBy":"Manager1","co":"India","extensionAttribute1":"Custom Value 1"}}}'

{
    "data": {
        "attributes": {
            "name": "APIOU1",
            "OUName": "OU=OUS,DC=domain,DC=com",
            "managedBy": "Manager1",
            "co": "India",
            "extensionAttribute1": "Custom Value 1"
        }
    }
}

{
    "data": [
        {
            "object": {
                "Container Name": "OU=OUs,DC=domain,DC=com",
                "OU Name": "APIOU1",
                "Distinguished Name": "OU=APIOU1,OU=OUS,DC=domain,DC=com",
                "Managed by": "CN=Manager 1,CN=Users,DC=domain,DC=com"
            },
            "status": {
                "status_code": 1,
                "status_message": "Successfully Updated."
            }
        }
    ],
    "meta": {
        "start_index": 1,
        "limit": 10,
        "total_no_of_objects": 1
    }
}

{
    "code": "00000100",
    "detail": "Some columns given in fields parameter are invalid",
    "title": "Bad Request."
}

{
    "code": "00000101",
    "detail": "The given Authtoken is invalid.",
    "title": "Unauthorized."
}

{
    "code": "00000000",
    "detail": "An internal server error occurred.",
    "title": "Internal Server Error."
}