Groups API

The Groups API provides programmatic access to Active Directory (AD) groups. It offers endpoints to update group attributes and retrieve group details using filters, sorting, and pagination, enabling administrators to automate and streamline group management. Group records typically include membership information, scope, and description fields, and the API ensures they can be accessed or modified in a consistent and secure format.

Download Groups API OpenAPI Document

End Points

GET

/groups

PATCH

/groups

List AD groups

The List AD Groups endpoint returns information about AD groups. You can refine results by applying filters, selecting specific fields, sorting the output, and using pagination to manage large datasets. This makes it easy to work with groups across one or more domains.

Scope : Read group action, All group management actions
Delegated role : All Groups Report

Query Parameters

from

integer

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

limit

integer

The maximum number of group records to return per request.

domains

string

(Required)

A comma-separated list of domains from which to fetch groups.
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.
Example: (SAM_ACCOUNT_NAME eq John) and (GROUP_NAME eq Doe)

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).
Example: SAM_ACCOUNT_NAME,-GROUP_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/groups?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/groups?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/groups?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/groups?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/groups?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/groups?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": [
        {
            "GROUP_NAME": "TestGroup1",
            "GROUP_SCOPE": "Universal",
            "DISTINGUISHED_NAME": "CN=TestGroup1,OU=Groups ou,DC=domain,DC=com",
            "OU_NAME": "Groups",
            "GROUP_TYPE": "Security",
            "SID_STRING": "S-1-5-21-829236456-16713239527-3165918102-24259",
            "OBJECT_GUID": "{3473E19D-48D1-4B65-8B9D-82923645627}",
            "MANAGER": "Manager1",
            "SAM_ACCOUNT_NAME": "TestGroup1"
        },
        {
            "GROUP_NAME": "TestGroup2",
            "GROUP_SCOPE": "Global",
            "DISTINGUISHED_NAME": "CN=TestGroup2,OU=Groups ou,DC=domain,DC=com",
            "OU_NAME": "Groups",
            "GROUP_TYPE": "Distribution",
            "SID_STRING": "S-1-5-21-829236456-16713239527-3165918102-24260",
            "OBJECT_GUID": "{3473E19D-48D1-4B65-8B9D-82923645628}",
            "MANAGER": "Manager2",
            "SAM_ACCOUNT_NAME": "TestGroup2"
        }
    ],
    "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 Groups

The Update AD Groups endpoint allows you to modify the properties of existing AD groups in bulk or individually. You can update core group details such as name, description, type, and OU, as well as advanced attributes like Exchange settings, membership, and nested group associations.
By sending the required payload, administrators can streamline group management tasks without needing to manually update groups from the ADManager Plus console.

Scope : Modify group action, All group management actions
Delegated role : Modify Groups Using CSV, Bulk Group Modification

Arguments

data

object

Data to be updated for the object.

Show Sub-Attributes

attributes

object

Attributes of the object to be updated. This can include Active directory attributes and Exchange attributes.

Show Sub-Attributes

sAMAccountName

string

The SAM account name of the group.

name

string

The name of the group.

description

string

The description of the group.

OUName

string

The OU where the group should reside.

mail

string

The email address of the group.

groupType

string

The type of the group (e.g., Security, Distribution).

member

string

The members of the group.

memberOf

string

Groups that this group should be a member.

info

string

Notes attribute of the group.

displayName

string

The display name of the group.

displayNamePrintable

string

The printable display name of the group.

preventDeletion

boolean

Indicates whether the group can be deleted.

exchange

object

Exchange-related attributes for the group.

Show Sub-Attributes

msExchAdminGroup

string

The administrative group associated with Exchange

mailNickname

string

The email alias of the group, used as the mail nickname in Exchange.

delivContLength

integer

The maximum delivery size (in KB) allowed for the group.

authOrig

string

List of senders who are allowed to send messages to this group's members.

unauthOrig

string

List of senders who are blocked from sending messages to this groups' members.

proxyAddresses

string

Collection of proxy email addresses assigned to the group.

msExchHideFromAddressLists

boolean

Indicates whether the group is hidden from the Exchange Global Address List (GAL).

Query Parameters

from

integer

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

limit

integer

The maximum number of group records to return per request.

domain

string

(Required)

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

filter

string

A SCIM filter query to refine which objects are returned. See Filter section for details.
Example: (SAM_ACCOUNT_NAME eq John) and (GROUP_NAME eq Doe)

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).
Example: SAM_ACCOUNT_NAME,-GROUP_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":{"sAMAccountName":"TestGroup2","name":"TestGroup2","accountNameHistory":"st9v9;s9t3s;9st5","memberOf":"TestGroup3;TestGroup4","exchange":{"msExchAdminGroup":"/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)","mailNickname":"TestGroup2","proxyAddresses":"SMTP:TestGroup2@domain.com"}}}}';
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/groups?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\":{\"sAMAccountName\":\"TestGroup2\",\"name\":\"TestGroup2\",\"accountNameHistory\":\"st9v9;s9t3s;9st5\",\"memberOf\":\"TestGroup3;TestGroup4\",\"exchange\":{\"msExchAdminGroup\":\"/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)\",\"mailNickname\":\"TestGroup2\",\"proxyAddresses\":\"SMTP:TestGroup2@domain.com\"}}}}");
Request request = new Request.Builder()
  .url("http://admanagerplus:8080/api/v2/groups?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":{"sAMAccountName":"TestGroup2","name":"TestGroup2","accountNameHistory":"st9v9;s9t3s;9st5","memberOf":"TestGroup3;TestGroup4","exchange":{"msExchAdminGroup":"/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)","mailNickname":"TestGroup2","proxyAddresses":"SMTP:TestGroup2@domain.com"}}}}'
};

fetch('http://admanagerplus:8080/api/v2/groups?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\":{\"sAMAccountName\":\"TestGroup2\",\"name\":\"TestGroup2\",\"accountNameHistory\":\"st9v9;s9t3s;9st5\",\"memberOf\":\"TestGroup3;TestGroup4\",\"exchange\":{\"msExchAdminGroup\":\"/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)\",\"mailNickname\":\"TestGroup2\",\"proxyAddresses\":\"SMTP:TestGroup2@domain.com\"}}}}"

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

conn.request("PATCH", "/api/v2/groups?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/groups?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: {
      sAMAccountName: 'TestGroup2',
      name: 'TestGroup2',
      accountNameHistory: 'st9v9;s9t3s;9st5',
      memberOf: 'TestGroup3;TestGroup4',
      exchange: {
        msExchAdminGroup: '/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)',
        mailNickname: 'TestGroup2',
        proxyAddresses: 'SMTP:TestGroup2@domain.com'
      }
    }
  }
}));
req.end();

curl --request PATCH \
  --url 'http://admanagerplus:8080/api/v2/groups?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":{"sAMAccountName":"TestGroup2","name":"TestGroup2","accountNameHistory":"st9v9;s9t3s;9st5","memberOf":"TestGroup3;TestGroup4","exchange":{"msExchAdminGroup":"/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)","mailNickname":"TestGroup2","proxyAddresses":"SMTP:TestGroup2@domain.com"}}}}'

{
    "data": {
        "attributes": {
            "sAMAccountName": "TestGroup2",
            "name": "TestGroup2",
            "accountNameHistory": "st9v9;s9t3s;9st5",
            "memberOf": "TestGroup3;TestGroup4",
            "exchange": {
                "msExchAdminGroup": "/o=Test/ou=Exchange Administrative Group (FYKLBOHF23SPDLT)",
                "mailNickname": "TestGroup2",
                "proxyAddresses": "SMTP:TestGroup2@domain.com"
            }
        }
    }
}

{
    "data": [
        {
            "object": {
                "SAM Account Name": "TestGroup2",
                "Distinguished Name": "CN=TestGroup2,OU=Groups,DC=domain,DC=com",
                "Email Proxy Addresses": "[SMTP:TestGroup2@domain.com]",
                "Name": "TestGroup2"
            },
            "status": {
                "status_code": 1,
                "status_message": "Successfully updated the group."
            }
        }
    ],
    "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."
}