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>"],
        },
        ...
    ],
    "o365": "<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. An OU or container can be identified by:

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

o365 `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");
        }
    );
    "o365" = @{
        "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']
                }
            ],
            'o365': {
                '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"]
        }
    ],
    "o365": {
        "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"]
        }
    ],
    "o365": {
        "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"]
        }
    ],
    "o365": {
        "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 on-premises AD

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 Azure AD

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

Name
Exchange alias
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=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": {}
}

Create directory object

Request parameters

Request headers

Request body

Common attributes

createIn string

objectType string

properties array

properties.propertyName string

properties.propertyType enum

properties.values value array

Type-specific attributes

o365 Microsoft365AccountProperties, optional

photo string, optional

photo string, optional

isPreWindows2000Computer bool

Responses

Examples

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

Request

Response

See also

createIn `string`

objectType `string`

properties `array`

properties.propertyName `string`

properties.propertyType `enum`

properties.values `value array`

o365 `Microsoft365AccountProperties`, `optional`

photo `string`, `optional`

photo `string`, `optional`

isPreWindows2000Computer `bool`