Modify directory object

Modifies properties of a directory object. This request can also be used to assign/revoke Microsoft 365 licenses of a user.

PATCH ~/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 can be included when modifying objects of any type, as well as type-specific attributes.

Any type
{
    "directoryObject": "<objectId>",
    "properties": [
        {
            "propertyName": "<propertyName>",
            "propertyType": "<propertyType>",
            "values": ["<newValue>"],
            "operation": "<operationType>",
            "mask": "<mask>"
        },
        ...
    ]
}
User
{
    "directoryObject": "<objectId>",
    "properties": [
        {
            "propertyName": "<propertyName>",
            "propertyType": "<propertyType>",
            "values": ["<newValue>"],
            "operation": "<operationType>",                
            "mask": "<mask>"
        },
        ...
    ],
    "m365": "<Microsoft365AccountProperties>",
    "photo": "<photo>"
}
Contact
{
    "directoryObject": "<objectId>",
    "properties": [
        {
            "propertyName": "<propertyName>",
            "propertyType": "<propertyType>",
            "values": ["<newValue>"],
            "operation": "<operationType>",
            "mask": "<mask>"
        },
        ...
    ],
    "photo": "<photo>"
}

Common attributes

directoryObject string

The identifier of the directory object to modify. You can use:

 Distinguished name (DN)
# Example
CN=John Smith,CN=Users,DC=example,DC=com
 Globally unique identifier (GUID)
# Example
7a4267ce-d354-44e7-8bd6-c681f1284a41
 Security identifier (SID)
# Example
S-1-5-21-3635565734-1729062999-1822655016-1627

properties array, optional

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

 Show attributes

properties.propertyName string

The name of the property to modify e.g. description, manager.

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 new property values.

  • To change the value of a single-valued property, specify the new value as a single array element.
  • To clear the current value, specify an empty array or null.
  • For details about changing values of certain properties, see Setting property values.

properties.operation enum, optional

Include this attribute only when modifying a multi-valued property. Specifies how the property should be updated:

  • Replace or 0 — to replace all existing values with the supplied values.
  • Append or 1 — to add the supplied values and keep existing values.
  • Delete or 2 — to delete existing values that match the supplied values.

If this attribute is not included in the request body, the Replace operation will be used by default.

 Examples

Replace all existing values of a property with two new values:

{
    "propertyName": "otherTelephone",
    "propertyType": "String",
    "operation": "Replace",
    "values": ["111-222-3333","444-555-6666"]
}

Add a new value to a property, and keep existing values:

{
    "propertyName": "otherTelephone",
    "propertyType": "String",
    "operation": "Append",
    "values": ["951-837-6935"]
}

Delete existing values of a property:

{
    "propertyName": "otherTelephone",
    "propertyType": "String",
    "operation": "Delete",
    "values": ["951-837-6935", "111-222-3333"]
}

properties.mask integer, optional

This attribute should only be included when modifying bitmask properties (e.g. userAccountControl or groupType). Specify a bitwise mask (in decimal) that should be applied to the new value.

For more details about using masks on the example of modifying account options, see Setting property values.

 Examples

Set the Password never expires flag:

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 65536 ],
    "mask": 65536
}

Clear the Password never expires flag:

{
    "propertyName": "userAccountControl",
    "propertyType": "Integer",
    "values": [ 0 ],
    "mask": 65536
}

Type-specific attributes

 User {id=user}

m365 Microsoft365AccountProperties, optional

An object representing Microsoft 365 account properties. Include this attribute in the request body to assign/revoke Microsoft 365 licenses of a 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.

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 – Update the user's telephone numbers

The following code sample updates the following properties of a user:

  • Telephone number
  • Telephone number (other) — new numbers are added to existing values.

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 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "telephoneNumber";
            "propertyType" = "String";
            "values" = @("605-457-8292")
        },
        @{
            "propertyName" = "otherTelephone";
            "propertyType" = "String";
            "operation" = "Append";
            "values" = @("951-837-6935","717-332-8612")
        }
    )
} 

# Make request
Invoke-RestMethod -Method PATCH -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 = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {
                    'propertyName': 'telephoneNumber',
                    'propertyType': 'String',
                    'values': ['605-457-8292']
                },
                {
                    'propertyName': 'otherTelephone',
                    'propertyType': 'String',
                    'operation': 'Append',
                    'values': ['951-837-6935','717-332-8612']
                }
            ]
        }";
        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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "telephoneNumber",
            "propertyType": "String",
            "values": ["605-457-8292"]
        },
        {
            "propertyName": "otherTelephone",
            "propertyType": "String",
            "operation": "Append",
            "values": ["951-837-6935","717-332-8612"]
        }
    ]
}'
node.js
var https = require('https');

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

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "telephoneNumber",
            "propertyType": "String",
            "values": ["605-457-8292"]
        },
        {
            "propertyName": "otherTelephone",
            "propertyType": "String",
            "operation": "Append",
            "values": ["951-837-6935","717-332-8612"]
        }
    ]
}`;

// 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 = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "telephoneNumber",
            "propertyType": "String",
            "values": ["605-457-8292"]
        },
        {
            "propertyName": "otherTelephone",
            "propertyType": "String",
            "operation": "Append",
            "values": ["951-837-6935","717-332-8612"]
        }
    ]
}

# Make request
request = requests.patch(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,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 2 – Remove the user's manager

The following code sample clears the user's Manager property.

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 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "manager";
            "propertyType" = "DN";
            "values" = @()
        }
    )
} 

# Make request
Invoke-RestMethod -Method PATCH -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 = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {
                    'propertyName': 'manager',
                    'propertyType': 'DN',
                    'values': []
                }
            ]
        }";
        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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "manager",
            "propertyType": "DN",
            "values": []
        }
    ]
}'
node.js
var https = require('https');

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

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "manager",
            "propertyType": "DN",
            "values": []
        }
    ]
}`;

// 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 = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "manager",
            "propertyType": "DN",
            "values": []
        }
    ]
}

# Make request
request = requests.patch(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,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 3 – Change the group scope

The following code sample changes an Active Directory group scope to Universal. For details about changing the group type/scope, see Setting property values.

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 @{
    "directoryObject" = "CN=My group,OU=Groups,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "groupType";
            "propertyType" = "Integer";
            "values" = @(8);  # ADS_GROUP_TYPE_UNIVERSAL_GROUP
            "mask" = 14 
        }
    )
} 

# Make request
Invoke-RestMethod -Method PATCH -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
        int newValue = 8; // ADS_GROUP_TYPE_UNIVERSAL_GROUP
        string jsonRequest = $@"
        {{
            'directoryObject': 'CN=My group,OU=Groups,DC=example,DC=com',
            'properties': [
                {{
                    'propertyName': 'groupType',
                    'propertyType': 'Integer',
                    'values': [ {newValue} ],
                    'mask': 14
                }}
            ]
        }}";
        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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=My group,OU=Groups,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "groupType",
            "propertyType": "Integer",
            "values": [ 8 ],
            "mask": 14
        }
    ]
}'
node.js
var https = require('https');

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

// Create JSON request body
var newValue = 8; // ADS_GROUP_TYPE_UNIVERSAL_GROUP
var postData = `
{
    "directoryObject": "CN=My group,OU=Groups,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "groupType",
            "propertyType": "Integer",
            "values": [ ${newValue} ], 
            "mask": 14
        }
    ]
}`;

// 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 = {
    "directoryObject": "CN=My group,OU=Groups,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "groupType",
            "propertyType": "Integer",
            "values": [ 8 ], # ADS_GROUP_TYPE_UNIVERSAL_GROUP
            "mask": 14
        }
    ]
}

# Make request
request = requests.patch(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=My group,OU=Groups,DC=example,DC=com",
    "extraInfo": {}
}
 Example 4 – Change the user's Account options

The following code sample updates the following Account options of a user:

  • Set the Password never expires flag
  • Clear the Account is disabled flag

For details about changing account options, see Setting property values.

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 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "userAccountControl";
            "propertyType" = "Integer";
            "values" = @(65536); # ADS_UF_DONT_EXPIRE_PASSWD
            "mask" = -2147418110 # ADS_UF_DONT_EXPIRE_PASSWD, ADS_UF_ACCOUNTDISABLE, ADAXES_UF_MUST_CHANGE_PASSWD_AT_LOGON
        }
    )
} 

# Make request
Invoke-RestMethod -Method PATCH -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
        int newValue = 65536; // ADS_UF_DONT_EXPIRE_PASSWD
        int mask = -2147418110; // ADS_UF_DONT_EXPIRE_PASSWD, ADS_UF_ACCOUNTDISABLE, ADAXES_UF_MUST_CHANGE_PASSWD_AT_LOGON
        string jsonRequest = $@"
        {{
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {{
                    'propertyName': 'userAccountControl',
                    'propertyType': 'Integer',
                    'values': [ {newValue} ],
                    'mask': {mask}
                }}
            ]
        }}";
        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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [ 65536 ],
            "mask": -2147418110
        }
    ]
}'
node.js
var https = require('https');

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

// Create JSON request body
var newValue = 65536; // ADS_UF_DONT_EXPIRE_PASSWD
var mask = -2147418110; // ADS_UF_DONT_EXPIRE_PASSWD, ADS_UF_ACCOUNTDISABLE, ADAXES_UF_MUST_CHANGE_PASSWD_AT_LOGON
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [ ${newValue} ],
            "mask": ${mask}
        }
    ]
}`;

// 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 = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [ 65536 ], # ADS_UF_DONT_EXPIRE_PASSWD
            "mask": -2147418110 # ADS_UF_DONT_EXPIRE_PASSWD, ADS_UF_ACCOUNTDISABLE, ADAXES_UF_MUST_CHANGE_PASSWD_AT_LOGON
        }
    ]
}

# Make request
request = requests.patch(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,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 5 – Revoke a Microsoft 365 license from a user

The following code sample revokes the specified Microsoft 365 license from a user.

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 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "m365" = @{
        "licenseModifications" = @(
            @{
                "skuPartNumber" = "ENTERPRISEPACK";
                "assigned" = $false
            }
        )
    }
} 

# Make request
Invoke-RestMethod -Method PATCH -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 = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'm365': {
                'licenseModifications': [
                    {
                        'skuPartNumber': 'ENTERPRISEPACK',
                        'assigned': 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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "m365": {
        "licenseModifications": [
            {
                "skuPartNumber": "ENTERPRISEPACK",
                "assigned": false
            }
        ]
    }
}'
node.js
var https = require('https');

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

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "m365": {
        "licenseModifications": [
            {
                "skuPartNumber": "ENTERPRISEPACK",
                "assigned": 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 = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "m365": {
        "licenseModifications": [
            {
                "skuPartNumber": "ENTERPRISEPACK",
                "assigned": False
            }
        ]
    }
}

# Make request
request = requests.patch(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,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 6 – Change the user's manager and account expiration

The following code sample updates the following properties of a user:

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 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "manager";
            "propertyType" = "DN";
            "values" = @("CN=Richard Roberts,CN=Users,DC=example,DC=com")
        },
        @{
            "propertyName" = "accountExpires";
            "propertyType" = "Timestamp";
            "values" = @("Never")
        }
    )
} 

# Make request
Invoke-RestMethod -Method PATCH -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 = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {
                    'propertyName': 'manager',
                    'propertyType': 'DN',
                    'values': [ 'CN=Richard Roberts,CN=Users,DC=example,DC=com' ]
                },
                {
                    'propertyName': 'accountExpires',
                    'propertyType': 'Timestamp',
                    'values': [ 'Never' ]
                }
            ]
        }";
        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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "manager",
            "propertyType": "DN",
            "values": [ "CN=Richard Roberts,CN=Users,DC=example,DC=com" ]
        },
        {
            "propertyName": "accountExpires",
            "propertyType": "Timestamp",
            "values": [ "Never" ]
        }
    ]
}'
node.js
var https = require('https');

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

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "manager",
            "propertyType": "DN",
            "values": [ "CN=Richard Roberts,CN=Users,DC=example,DC=com" ]
        },
        {
            "propertyName": "accountExpires",
            "propertyType": "Timestamp",
            "values": [ "Never" ]
        }
    ]
}`;

// 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 = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "manager",
            "propertyType": "DN",
            "values": [ "CN=Richard Roberts,CN=Users,DC=example,DC=com" ]
        },
        {
            "propertyName": "accountExpires",
            "propertyType": "Timestamp",
            "values": [ "Never" ]
        }
    ]
}

# Make request
request = requests.patch(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,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 7 – Rename a user

The following code sample changes the name of a user.

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 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "name";
            "propertyType" = "String";
            "values" = @("John Raymond")
        }
    )
} 

# Make request
Invoke-RestMethod -Method PATCH -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 = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {
                    'propertyName': 'name',
                    'propertyType': 'String',
                    'values': [ 'John Raymond' ]
                }
            ]
        }";
        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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "name",
            "propertyType": "String",
            "values": [ "John Raymond" ]
        }
    ]
}'
node.js
var https = require('https');

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

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "name",
            "propertyType": "String",
            "values": [ "John Raymond" ]
        }
    ]
}`;

// 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 = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "name",
            "propertyType": "String",
            "values": [ "John Raymond" ]
        }
    ]
}

# Make request
request = requests.patch(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 Raymond,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}
 Example 8 – Disable a user account

The following code sample disables a user account. For details about changing account options, see Setting property values.

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 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "userAccountControl";
            "propertyType" = "Integer";
            "values" = @(2); # ADS_UF_ACCOUNTDISABLE
            "mask" = 2
        }
    )
} 

# Make request
Invoke-RestMethod -Method PATCH -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
        int newValue = 2; // ADS_UF_ACCOUNTDISABLE
        int mask = newValue;
        string jsonRequest = $@"
        {{
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {{
                    'propertyName': 'userAccountControl',
                    'propertyType': 'Integer',
                    'values': [ {newValue} ],
                    'mask': {mask}
                }}
            ]
        }}";
        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.PatchAsync(
            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 PATCH 'https://host.example.com/restApi/api/directoryObjects' \
--data-raw '{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [ 2 ],
            "mask": 2
        }
    ]
}'
node.js
var https = require('https');

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

// Create JSON request body
var newValue = 2; // ADS_UF_ACCOUNTDISABLE
var mask = newValue; 
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [ ${newValue} ],
            "mask": ${mask}
        }
    ]
}`;

// 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 = {
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "properties": [
        {
            "propertyName": "userAccountControl",
            "propertyType": "Integer",
            "values": [ 2 ], # ADS_UF_ACCOUNTDISABLE
            "mask": 2
        }
    ]
}

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

You can also disable accounts using the Disable account request.

Response

HTTP Status code: 200 OK
Response body:

{
    "resultType": 0,
    "innerMessages": [],
    "exception": null,
    "actualObjectDN": "CN=John Smith,CN=Users,DC=example,DC=com",
    "extraInfo": {}
}

See also

© Softerra 2022. All rights reserved.
Send feedback