Sorry, search feature is not supported in Internet Explorer 11

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

 Distinguished name (DN) {.black}
# Example
CN=John Smith,CN=Users,DC=example,DC=com
 Globally unique identifier (GUID) {.black}
# Example
7a4267ce-d354-44e7-8bd6-c681f1284a41
 Security identifier (SID) {.black}
# 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 LDAP name of the property to modify e.g. description, managedBy.


properties.propertyType enum
The property type.

Show possible enum values

DnString           = 1,  // DN syntax properties e.g. Manager or Assistant
CaseExactString    = 2,  // Case-sensitive string
CaseIgnoreString   = 3,  // Case-insensitive string
PrintableString    = 4,  // Printable string
NumericString      = 5,  // Numeric string
Boolean            = 6,  // Boolean
Integer            = 7,  // Integer
OctetString        = 8,  // Octet string
UtcTime            = 9,  // Generalized time
LargeInteger       = 10, // Large integer
Timestamp          = 14, // Timestamp
LogonHours         = 19  // Logon hours

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": "CaseIgnoreString",
    "operation": "Replace",
    "values": ["111-222-3333","444-555-6666"]
}

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

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

Delete existing values of a property:

{
    "propertyName": "otherTelephone",
    "propertyType": "CaseIgnoreString",
    "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}

o365 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"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestBody = ConvertTo-Json -Depth 3 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "telephoneNumber";
            "propertyType" = "CaseIgnoreString";
            "values" = @("605-457-8292")
        },
        @{
            "propertyName" = "otherTelephone";
            "propertyType" = "CaseIgnoreString";
            "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";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {
                    'propertyName': 'telephoneNumber',
                    'propertyType': 'CaseIgnoreString',
                    'values': ['605-457-8292']
                },
                {
                    'propertyName': 'otherTelephone',
                    'propertyType': 'CaseIgnoreString',
                    'operation': 'Append',
                    'values': ['951-837-6935','717-332-8612']
                }
            ]
        }";
        StringContent requestBody = new StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", 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: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--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": "CaseIgnoreString",
            "values": ["605-457-8292"]
        },
        {
            "propertyName": "otherTelephone",
            "propertyType": "CaseIgnoreString",
            "operation": "Append",
            "values": ["951-837-6935","717-332-8612"]
        }
    ]
}'
node.js
var https = require('https');

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

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

// Make request
var req = https.request(options, function (res) {
    var chunks = [];

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

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

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

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: Change the group scope

The following code sample changes the 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"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$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";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // 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 StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", 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: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--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 and headers
var options = {
    'method': 'PATCH',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD',
        '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, function (res) {
    var chunks = [];

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

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

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

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 3: 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"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$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";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // 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 StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", 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: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--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 and headers
var options = {
    'method': 'PATCH',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD',
        '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, function (res) {
    var chunks = [];

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

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

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

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 4: 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"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestBody = ConvertTo-Json -Depth 4 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "o365" = @{
        "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";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'o365': {
                'licenseModifications': [
                    {
                        'skuPartNumber': 'ENTERPRISEPACK',
                        'assigned': false
                    }
                ]
            }
        }";
        StringContent requestBody = new StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", 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: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--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",
    "o365": {
        "licenseModifications": [
            {
                "skuPartNumber": "ENTERPRISEPACK",
                "assigned": false
            }
        ]
    }
}'
node.js
var https = require('https');

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

// Create JSON request body
var postData = `
{
    "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com",
    "o365": {
        "licenseModifications": [
            {
                "skuPartNumber": "ENTERPRISEPACK",
                "assigned": false
            }
        ]
    }
}`;

// Make request
var req = https.request(options, function (res) {
    var chunks = [];

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

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

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

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: 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"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestBody = ConvertTo-Json -Depth 3 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "manager";
            "propertyType" = "DnString";
            "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";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {
                    'propertyName': 'manager',
                    'propertyType': 'DnString',
                    'values': [ 'CN=Richard Roberts,CN=Users,DC=example,DC=com' ]
                },
                {
                    'propertyName': 'accountExpires',
                    'propertyType': 'Timestamp',
                    'values': [ 'Never' ]
                }
            ]
        }";
        StringContent requestBody = new StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", 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: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--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": "DnString",
            "values": [ "CN=Richard Roberts,CN=Users,DC=example,DC=com" ]
        },
        {
            "propertyName": "accountExpires",
            "propertyType": "Timestamp",
            "values": [ "Never" ]
        }
    ]
}'
node.js
var https = require('https');

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

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

// Make request
var req = https.request(options, function (res) {
    var chunks = [];

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

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

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

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: Rename a user

The following code sample changes the name of a user.

Request

PowerShell
$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestBody = ConvertTo-Json -Depth 3 @{
    "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com";
    "properties" = @(
        @{
            "propertyName" = "name";
            "propertyType" = "CaseIgnoreString";
            "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";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // Create JSON request body
        string jsonRequest = @"
        {
            'directoryObject': 'CN=John Smith,CN=Users,DC=example,DC=com',
            'properties': [
                {
                    'propertyName': 'name',
                    'propertyType': 'CaseIgnoreString',
                    'values': [ 'John Raymond' ]
                }
            ]
        }";
        StringContent requestBody = new StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", 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: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--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": "CaseIgnoreString",
            "values": [ "John Raymond" ]
        }
    ]
}'
node.js
var https = require('https');

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

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

// Make request
var req = https.request(options, function (res) {
    var chunks = [];

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

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

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

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 7: 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"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$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";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        // 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 StringContent(
            jsonRequest, Encoding.UTF8, "application/json");

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", 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: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--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 and headers
var options = {
    'method': 'PATCH',
    'hostname': 'host.example.com',
    'path': '/restApi/api/directoryObjects',
    'headers': {
        'Adm-Authorization': 'HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD',
        '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, function (res) {
    var chunks = [];

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

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

    res.on("error", function (error) {
        console.error(error);
    });
});

req.write(postData);

req.end();

Tip

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