Create directory object

Creates a directory object.

POST ~/api/directoryObjects

Request parameters

This request has no parameters.

Request headers

  • Name

  • Required

  • Description

  • Adm-Authorization

  • True

  • Specify the security token obtained during authentication.

  • Content-Type

  • True

  • Use application/json as the value of this header.

Request body

The request body is a JSON object with the following data structure. It has common attributes that must be included when creating objects of any type, as well as type-specific attributes.

Any type
{
    "createIn": "<containerID>",
    "objectType": "<objectType>",
    "properties": [
        {
            "propertyName": "<propertyName>",
            "propertyType": "<propertyType>",
            "values": ["<propertyValue>"],
        },
        ...
    ]
}
User
{
    "createIn": "<containerID>",
    "objectType": "user",
    "properties": [
        {
            "propertyName": "<propertyName>",
            "propertyType": "<propertyType>",
            "values": ["<propertyValue>"],
        },
        ...
    ],
    "m365": "<Microsoft365AccountProperties>",
    "photo": "<photo>"
}
Contact
{
    "createIn": "<containerID>",
    "objectType": "contact",
    "properties": [
        {
            "propertyName": "<propertyName>",
            "propertyType": "<propertyType>",
            "values": ["<propertyValue>"],
        },
        ...
    ],
    "photo": "<photo>"
}
Computer
{
    "createIn": "<containerID>",
    "objectType": "computer",
    "properties": [
        {
            "propertyName": "<propertyName>",
            "propertyType": "<propertyType>",
            "values": ["<propertyValue>"],
        },
        ...
    ],
    "isPreWindows2000Computer": <true|false>
}

Common attributes

createIn string

The identifier of the organizational unit or container where to create the object. You can use:

 Distinguished name (DN)
# Example
OU=My Organizational Unit,DC=example,DC=com
 Globally unique identifier (GUID)
# Example
0b4d238a-62fc-4088-0ff3-4ae2b108eed4

objectType string

The object class of the new object.

 Examples
objectType Display name
organizationalUnit Organizational Unit
container Container
user User
contact Contact
group Group
computer Computer
printQueue Printer
volume Shared folder

properties array

An array of items, each representing a specific property of the new directory object.

 Show attributes

properties.propertyName string

The name of the property which you would like to set e.g. givenName, sn.

properties.propertyType enum

The property type.

 Show possible enum values
DN                 = 1,  // DN syntax properties e.g. Manager or Assistant
String             = 2,  // Case-sensitive string
Boolean            = 6,  // Boolean
Integer            = 7,  // Integer
Binary             = 8,  // Binary properties e.g. Logon Hours property
DateTime           = 9,  // Generalized time
LargeInteger       = 10, // Large integer
Timestamp          = 14, // Timestamp

properties.values value array

An array of property values. To set the value for a single-valued property, specify it as a single element of the array. For details about setting values of certain properties, see Setting property values.

Type-specific attributes

 User

m365 Microsoft365AccountProperties, optional

An object representing Microsoft 365 account properties. Include this attribute in the request body to assign Microsoft 365 licenses to the created user. For details, see Microsoft 365 account properties.

photo string, optional

A Base64-encoded string that represents the user's photo.

 Contact

photo string, optional

A Base64-encoded string that represents the contact's photo.

 Computer

isPreWindows2000Computer bool

Set to true to assign this computer as a pre-Windows 2000 computer.

Responses

If successful, returns 200 OK status code and an operation result in the response body. Otherwise, returns one of the common HTTP error codes and an error description in the response body.

Examples

 Example 1 – Create a user

The following code sample creates a user account with the following properties:

  • First name
  • Last name
  • Full name
  • Username
  • Password
  • Account options (see details)
  • Account expires (see details)

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 4 @{
    "createIn" = "OU=My Organizational Unit,DC=example,DC=com";
    "objectType" = "user";
    "properties" = @(
        @{
            "propertyName" = "cn";
            "propertyType" = "String";
            "values" = @("John Smith")
        },
        @{
            "propertyName" = "givenName";
            "propertyType" = "String";
            "values" = @("John")
        },
        @{
            "propertyName" = "sn";
            "propertyType" = "String";
            "values" = @("Smith")
        },
        @{
            "propertyName" = "userPrincipalName";
            "propertyType" = "String";
            "values" = @("jsmith")
        },
        @{
            "propertyName" = "unicodePwd";
            "propertyType" = "String";
            "values" = @("MyPassword1!")
        },
        @{
            "propertyName" = "userAccountControl";
            "propertyType" = "Integer";
            "values" = @(-2147483136)
        },
        @{
            "propertyName" = "accountExpires";
            "propertyType" = "Timestamp";
            "values" = @("2020-12-15T18:00:00+03:00")
        }
    )
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {   
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'createIn': 'OU=My Organizational Unit,DC=example,DC=com',
            'objectType': 'user',
            'properties': [
                {
                    'propertyName': 'cn',
                    'propertyType': 'String',
                    'values': ['John Smith']
                },
                {
                    'propertyName': 'givenName',
                    'propertyType': 'String',
                    'values': ['John']
                },
                {
                    'propertyName': 'sn',
                    'propertyType': 'String',
                    'values': ['Smith']
                },
                {
                    'propertyName': 'userPrincipalName',
                    'propertyType': 'String',
                    'values': ['jsmith']
                },
                {
                    'propertyName': 'unicodePwd',
                    'propertyType': 'String',
                    'values': ['MyPassword1!']
                },
                {
                    'propertyName': 'userAccountControl',
                    'propertyType': 'Integer',
                    'values': [-2147483136]
                },
                {
                    'propertyName': 'accountExpires',
                    'propertyType': 'Timestamp',
                    'values': [ '2020-12-15T18:00:00+03:00' ]
                }
            ]
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "user",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["John Smith"]
        },
        {
            "propertyName": "givenName",
            "propertyType": "String",
            "values": ["John"]
        },
        {
            "propertyName": "sn",
            "propertyType": "String",
            "values": ["Smith"]
        },
        {
            "propertyName": "userPrincipalName",
            "propertyType": "String",
            "values": ["jsmith"]
        },
        {
            "propertyName": "unicodePwd",
            "propertyType": "String",
            "values": ["MyPassword1!"]
        },
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [-2147483136]
        },
        {
            "propertyName": "accountExpires",
            "propertyType": "Timestamp",
            "values": [ "2020-12-15T18:00:00+03:00" ]
        }
    ]
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "user",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["John Smith"]
        },
        {
            "propertyName": "givenName",
            "propertyType": "String",
            "values": ["John"]
        },
        {
            "propertyName": "sn",
            "propertyType": "String",
            "values": ["Smith"]
        },
        {
            "propertyName": "userPrincipalName",
            "propertyType": "String",
            "values": ["jsmith"]
        },
        {
            "propertyName": "unicodePwd",
            "propertyType": "String",
            "values": ["MyPassword1!"]
        },
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [-2147483136]
        },
        {
            "propertyName": "accountExpires",
            "propertyType": "Timestamp",
            "values": [ "2020-12-15T18:00:00+03:00" ]
        }
    ]
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "user",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["John Smith"]
        },
        {
            "propertyName": "givenName",
            "propertyType": "String",
            "values": ["John"]
        },
        {
            "propertyName": "sn",
            "propertyType": "String",
            "values": ["Smith"]
        },
        {
            "propertyName": "userPrincipalName",
            "propertyType": "String",
            "values": ["jsmith"]
        },
        {
            "propertyName": "unicodePwd",
            "propertyType": "String",
            "values": ["MyPassword1!"]
        },
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [-2147483136]
        },
        {
            "propertyName": "accountExpires",
            "propertyType": "Timestamp",
            "values": [ "2020-12-15T18:00:00+03:00" ]
        }
    ]
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "CN=John Smith,OU=My Organizational Unit,DC=example,DC=com",
    "extraInfo": {}
}
 Example 2 – Create a user and assign Microsoft 365 licenses

The following code sample creates a user account and assigns the Microsoft 365 Apps for business license if the user is created successfully:

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 5 @{
    "createIn" = "OU=My Organizational Unit,DC=example,DC=com";
    "objectType" = "user";
    "properties" = @(
        @{
            "propertyName" = "givenName";
            "propertyType" = "String";
            "values" = @("John")
        },
        @{
            "propertyName" = "sn";
            "propertyType" = "String";
            "values" = @("Smith")
        },
        @{
            "propertyName" = "userPrincipalName";
            "propertyType" = "String";
            "values" = @("jsmith");
        }
    );
    "m365" = @{
        "locationName" = "US";
        "signInBlocked" = $false;
        "licenseModifications" = @(
            @{
                "skuPartNumber" = "O365_BUSINESS";
                "assigned" = $true
            }
        )
    }
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {   
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'createIn': 'OU=My Organizational Unit,DC=example,DC=com',
            'objectType': 'user',
            'properties': [
                {
                    'propertyName': 'givenName',
                    'propertyType': 'String',
                    'values': ['John']
                },
                {
                    'propertyName': 'sn',
                    'propertyType': 'String',
                    'values': ['Smith']
                },
                {
                    'propertyName': 'userPrincipalName',
                    'propertyType': 'String',
                    'values': ['jsmith']
                }
            ],
            'm365': {
                'locationName': 'US',
                'signInBlocked': false,
                'licenseModifications': [
                    {
                        'skuPartNumber': 'O365_BUSINESS',
                        'assigned': true
                        
                    }
                ]
            }
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "user",
    "properties": [
        {
            "propertyName": "givenName",
            "propertyType": "String",
            "values": ["John"]
        },
        {
            "propertyName": "sn",
            "propertyType": "String",
            "values": ["Smith"]
        },
        {
            "propertyName": "userPrincipalName",
            "propertyType": "String",
            "values": ["jsmith"]
        }
    ],
    "m365": {
        "locationName": "US",
        "signInBlocked": false,
        "licenseModifications": [
            {
                "skuPartNumber": "O365_BUSINESS",
                "assigned": true
                
            }
        ]
    }
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "user",
    "properties": [
        {
            "propertyName": "givenName",
            "propertyType": "String",
            "values": ["John"]
        },
        {
            "propertyName": "sn",
            "propertyType": "String",
            "values": ["Smith"]
        },
        {
            "propertyName": "userPrincipalName",
            "propertyType": "String",
            "values": ["jsmith"]
        }
    ],
    "m365": {
        "locationName": "US",
        "signInBlocked": false,
        "licenseModifications": [
            {
                "skuPartNumber": "O365_BUSINESS",
                "assigned": true
            }
        ]
    }
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "user",
    "properties": [
        {
            "propertyName": "givenName",
            "propertyType": "String",
            "values": ["John"]
        },
        {
            "propertyName": "sn",
            "propertyType": "String",
            "values": ["Smith"]
        },
        {
            "propertyName": "userPrincipalName",
            "propertyType": "String",
            "values": ["jsmith"]
        }
    ],
    "m365": {
        "locationName": "US",
        "signInBlocked": False,
        "licenseModifications": [
            {
                "skuPartNumber": "O365_BUSINESS",
                "assigned": True
            }
        ]
    }
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "exception": null,
    "innerMessages": [
        {
            "source": null,
            "text": "A temporary password has been assigned to the user's Microsoft 365 account. The temporary password is Rg8^6H#c.",
            "messageType": 2,
            "innerMessages": []
        }
    ],
    "actualObjectDN": "CN=John Smith,OU=My Organizational Unit,DC=example,DC=com",
    "extraInfo": {}
}
 Example 3 – Create a group in Active Directory

The following code sample creates a universal security group with the following properties:

  • Name
  • Managed By
  • CustomAttributeBoolean1 (Adaxes virtual property)
  • Group type (see details)

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 4 @{
    "createIn" = "OU=My Organizational Unit,DC=example,DC=com";
    "objectType" = "group";
    "properties" = @(
        @{
            "propertyName" = "cn";
            "propertyType" = "String";
            "values" = @("New Group")
        },
        @{
            "propertyName" = "groupType";
            "propertyType" = "Integer";
            "values" = @(-2147483640)
        },
        @{
            "propertyName" = "managedBy";
            "propertyType" = "DN";
            "values" = @("CN=John Smith,OU=My Organizational Unit,DC=example,DC=com")
        },
        @{
            "propertyName" = "adm-CustomAttributeBoolean1";
            "propertyType" = "Boolean";
            "values" = @($true)
        }
    )
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {   
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'createIn': 'OU=My Organizational Unit,DC=example,DC=com',
            'objectType': 'group',
            'properties': [
                {
                    'propertyName': 'cn',
                    'propertyType': 'String',
                    'values': ['New Group']
                },
                {
                    'propertyName': 'groupType',
                    'propertyType': 'Integer',
                    'values': [-2147483640]
                },
                {
                    'propertyName': 'managedBy',
                    'propertyType': 'DN',
                    'values': ['CN=John Smith,OU=My Organizational Unit,DC=example,DC=com']
                },
                {
                    'propertyName': 'adm-CustomAttributeBoolean1',
                    'propertyType': 'Boolean',
                    'values': [true]
                }
            ]
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "group",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["New Group"]
        },
        {
            "propertyName": "groupType",
            "propertyType": "Integer",
            "values": [-2147483640]
        },
        {
            "propertyName": "managedBy",
            "propertyType": "DN",
            "values": ["CN=John Smith,OU=My Organizational Unit,DC=example,DC=com"]
        },
        {
            "propertyName": "adm-CustomAttributeBoolean1",
            "propertyType": "Boolean",
            "values": [true]
        }
    ]
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "group",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["New Group"]
        },
        {
            "propertyName": "groupType",
            "propertyType": "Integer",
            "values": [-2147483640]
        },
        {
            "propertyName": "managedBy",
            "propertyType": "DN",
            "values": ["CN=John Smith,OU=My Organizational Unit,DC=example,DC=com"]
        },
        {
            "propertyName": "adm-CustomAttributeBoolean1",
            "propertyType": "Boolean",
            "values": [true]
        }
    ]
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "group",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["New Group"]
        },
        {
            "propertyName": "groupType",
            "propertyType": "Integer",
            "values": [-2147483640]
        },
        {
            "propertyName": "managedBy",
            "propertyType": "DN",
            "values": ["CN=John Smith,OU=My Organizational Unit,DC=example,DC=com"]
        },
        {
            "propertyName": "adm-CustomAttributeBoolean1",
            "propertyType": "Boolean",
            "values": [True]
        }
    ]
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "CN=New Group,OU=My Organizational Unit,DC=example,DC=com",
    "extraInfo": {}
}
 Example 4 – Create a group in Microsoft Entra ID

The following code sample creates a Microsoft 365 group with the following properties:

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 4 @{
    "createIn" = "OU=Groups,DC=example,DC=onmicrosoft,DC=com";
    "objectType" = "group";
    "properties" = @(
        @{
            "propertyName" = "cn";
            "propertyType" = "String";
            "values" = @("New Group")
        },
        @{
            "propertyName" = "adm-AzureGroupType";
            "propertyType" = "Integer";
            "values" = @(1)
        },
        @{
            "propertyName" = "mailNickname";
            "propertyType" = "String";
            "values" = @("new-group")
        }
    )
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {   
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'createIn': 'OU=Groups,DC=example,DC=onmicrosoft,DC=com',
            'objectType': 'group',
            'properties': [
                {
                    'propertyName': 'cn',
                    'propertyType': 'String',
                    'values': ['New Group']
                },
                {
                    'propertyName': 'adm-AzureGroupType',
                    'propertyType': 'Integer',
                    'values': [1]
                },
                {
                    'propertyName': 'mailNickName',
                    'propertyType': 'String',
                    'values': ['new-group']
                }
            ]
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "createIn": "OU=Groups,DC=example,DC=onmicrosoft,DC=com",
    "objectType": "group",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["New Group"]
        },
        {
            "propertyName": "adm-AzureGroupType",
            "propertyType": "Integer",
            "values": [1]
        },
        {
            "propertyName": "mailNickName",
            "propertyType": "String",
            "values": ["new-group"]
        }
    ]
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "createIn": "OU=Groups,DC=example,DC=onmicrosoft,DC=com",
    "objectType": "group",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["New Group"]
        },
        {
            "propertyName": "adm-AzureGroupType",
            "propertyType": "Integer",
            "values": [1]
        },
        {
            "propertyName": "mailNickName",
            "propertyType": "String",
            "values": ["new-group"]
        }
    ]
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "createIn": "OU=Groups,DC=example,DC=onmicrosoft,DC=com",
    "objectType": "group",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["New Group"]
        },
        {
            "propertyName": "adm-AzureGroupType",
            "propertyType": "Integer",
            "values": [1]
        },
        {
            "propertyName": "mailNickName",
            "propertyType": "String",
            "values": ["new-group"]
        }
    ]
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "CN=New Group\\0AUID:6b264db2a48a453e8b90b40929db0a0a,
        OU=Groups,DC=example,DC=onmicrosoft,DC=com",
    "extraInfo": {}
}
 Example 5 – Create an organizational unit

The following code sample creates an organizational unit with the following properties:

  • Name
  • Description (multi-line)
  • Protected from accidental deletion

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 3 @{
    "createIn" = "OU=My Organizational Unit,DC=example,DC=com";
    "objectType" = "organizationalUnit";
    "properties" = @(
        @{
            "propertyName" = "ou";
            "propertyType" = "String";
            "values" = @("New Organizational Unit")
        },
        @{
            "propertyName" = "description";
            "propertyType" = "String";
            "values" = @("Line 1`r`nLine 2")
        },
        @{
            "propertyName" = "adm-ProtectedFromDeletion";
            "propertyType" = "Boolean";
            "values" = @($true)
        }
    )
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {   
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'createIn': 'OU=My Organizational Unit,DC=example,DC=com',
            'objectType': 'organizationalUnit',
            'properties': [
                {
                    'propertyName': 'ou',
                    'propertyType': 'String',
                    'values': ['New Organizational Unit']
                },
                {
                    'propertyName': 'description',
                    'propertyType': 'String',
                    'values': ['Line 1\r\nLine 2']
                },
                {
                    'propertyName': 'adm-ProtectedFromDeletion',
                    'propertyType': 'Boolean',
                    'values':  [ true ]
                }
            ]
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "organizationalUnit",
    "properties": [
        {
            "propertyName": "ou",
            "propertyType": "String",
            "values": ["New Organizational Unit"]
        },
        {
            "propertyName": "description",
            "propertyType": "String",
            "values": ["Line 1\r\nLine 2"]
        },
        {
            "propertyName": "adm-ProtectedFromDeletion",
            "propertyType": "Boolean",
            "values":  [ true ]
        }
    ]
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "organizationalUnit",
    "properties": [
        {
            "propertyName": "ou",
            "propertyType": "String",
            "values": ["New Organizational Unit"]
        },
        {
            "propertyName": "description",
            "propertyType": "String",
            "values": ["Line 1\r\nLine 2"]
        },
        {
            "propertyName": "adm-ProtectedFromDeletion",
            "propertyType": "Boolean",
            "values":  [ true ]
        }
    ]
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "organizationalUnit",
    "properties": [
        {
            "propertyName": "ou",
            "propertyType": "String",
            "values": ["New Organizational Unit"]
        },
        {
            "propertyName": "description",
            "propertyType": "String",
            "values": ["Line 1\r\nLine 2"]
        },
        {
            "propertyName": "adm-ProtectedFromDeletion",
            "propertyType": "Boolean",
            "values":  [True]
        }
    ]
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "OU=New Organizational Unit,OU=My Organizational Unit,DC=example,DC=com",
    "extraInfo": {}
}
 Example 6 – Create a computer

The following code sample creates a computer with the following properties:

  • Name
  • NetBIOS name
  • Can be joined to domain by

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"

# Request parameters
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN}
$requestBody = ConvertTo-Json -Depth 3 @{
    "createIn" = "OU=My Organizational Unit,DC=example,DC=com";
    "objectType" = "computer";
    "properties" = @(
        @{
            "propertyName" = "cn";
            "propertyType" = "String";
            "values" = @("NEWCOMPUTER")
        },
        @{
            "propertyName" = "adm-userOrGroupThatCanJoinComputerToDomain";
            "propertyType" = "DN";
            "values" = @("CN=Michael Smith,OU=My Organizational Unit,DC=example,DC=com");
        }
    )
    "isPreWindows2000Computer" = $false
} 

# Make request
Invoke-RestMethod -Method POST -Headers $requestHeaders -Uri $requestUrl `
    -Body $requestBody -ContentType "application/json"
C#
using System;
using System.Text;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {   
        const string baseUrl = "https://host.example.com/restApi";
        const string endpoint = "/api/directoryObjects";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'createIn': 'OU=My Organizational Unit,DC=example,DC=com',
            'objectType': 'computer',
            'properties': [
                {
                    'propertyName': 'cn',
                    'propertyType': 'String',
                    'values': ['NEWCOMPUTER']
                },
                {
                    'propertyName': 'adm-userOrGroupThatCanJoinComputerToDomain',
                    'propertyType': 'DN',
                    'values': ['CN=Michael Smith,OU=My Organizational Unit,DC=example,DC=com']
                }
            ],
            'isPreWindows2000Computer': false
        }";
        StringContent requestBody = new(jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using HttpClient client = new();
        client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN);

        // Make request
        HttpResponseMessage response = await client.PostAsync(
            baseUrl + endpoint, requestBody);
        string responseBody = response.Content.ReadAsStringAsync().Result;
        Console.WriteLine(responseBody);
    }
}
cURL
curl  --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \
--header 'Content-Type: application/json' \
--request POST 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "computer",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["NEWCOMPUTER"]
        },
        {
            "propertyName": "adm-userOrGroupThatCanJoinComputerToDomain",
            "propertyType": "DN",
            "values": ["CN=Michael Smith,OU=My Organizational Unit,DC=example,DC=com"]
        }
    ],
    "isPreWindows2000Computer": false
}'
node.js
var https = require('https');

// Request parameters
var options = {
    'method': 'POST',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'YOUR-SECURITY-TOKEN',
        'Content-Type': 'application/json'
    }
};

// Create JSON request body
var postData = `
{
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "computer",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["NEWCOMPUTER"]
        },
        {
            "propertyName": "adm-userOrGroupThatCanJoinComputerToDomain",
            "propertyType": "DN",
            "values": ["CN=Michael Smith,OU=My Organizational Unit,DC=example,DC=com"]
        }
    ],
    "isPreWindows2000Computer": false
}`;

// Make request
var req = https.request(options, res => {
    var data = [];

    res.on("data", chunk => {
        data.push(chunk);
    });

    res.on("end", () => {
        var body = Buffer.concat(data);
        console.log(body.toString());
    });

    res.on("error", error => {
        console.error(error);
    });
});
req.write(postData);

req.end();
Python
import requests
import json

baseUrl = "https://host.example.com/restApi"
endpoint = "/api/directoryObjects"

# Request parameters
requestUrl = baseUrl + endpoint
requestHeaders = {"Adm-Authorization": YOUR-SECURITY-TOKEN}
requestBody = {
    "createIn": "OU=My Organizational Unit,DC=example,DC=com",
    "objectType": "computer",
    "properties": [
        {
            "propertyName": "cn",
            "propertyType": "String",
            "values": ["NEWCOMPUTER"]
        },
        {
            "propertyName": "adm-userOrGroupThatCanJoinComputerToDomain",
            "propertyType": "DN",
            "values": ["CN=Michael Smith,OU=My Organizational Unit,DC=example,DC=com"]
        }
    ],
    "isPreWindows2000Computer": False
}

# Make request
request = requests.post(requestUrl, headers=requestHeaders, json=requestBody)
response = json.loads(request.content)
print(response)

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "CN=NEWCOMPUTER,OU=My Organizational Unit,DC=example,DC=com",
    "extraInfo": {}
}

See also

© Softerra 2022. All rights reserved.
Send feedback