Sorry, search feature is not supported in Internet Explorer 11

Get directory object

Retrieves a directory object.

GET ~/api/directoryObjects?<parameters>

Query parameters

  • Name

  • Required

  • Type

  • Description

  • directoryObject

  • True

  • string

  • The identifier of the directory object to retrieve. 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

  • False

  • string

  • A comma-separated list of LDAP property names without whitespaces e.g. manager,department to retrieve If not specified, the object will be retrieved with the default property set.

     Default property set {.black}
    • guid
    • dn
    • displayName
    • objectType
    • objectTypeCode
    • domainName

Request headers

  • Name

  • Required

  • Description

  • Adm-Authorization

  • True

  • Specify the security token obtained during authentication.

Request body

Do not send a body with this request.

Responses

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

Examples

 Example 1: Retrieve a user

The following code sample retrieves a user object using only the mandatory request parameters.

Request

PowerShell
$userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestParams = @{directoryObject = $userIdentifier}

# Make request
Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
C#
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com";   
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        UriBuilder requestUrl = new UriBuilder(
            "https://host.example.com/restApi/api/directoryObjects");
        requestUrl.Query += $"?directoryObject={userIdentifier}";

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", token);

            // Make request
            string response = await client.GetStringAsync(requestUrl.ToString());
            Console.WriteLine(response);
        }
    }
}
cURL
curl  --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--get -X GET 'https://host.example.com/restApi/api/directoryObjects' \
--data-urlencode 'directoryobject=CN=John Smith,CN=Users,DC=example,DC=com'
node.js
var userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com";

var https = require("https");

// Request parameters and headers
var requestPath = "/restApi/api/directoryObjects"
  + `?directoryobject=${userIdentifier}`;

var options = {
    'method': 'GET',
    'hostname': 'host.example.com',
    'path': encodeURI(requestPath),
    'headers': {
        "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD",
    }
};

// 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.end();

Response

HTTP Status code: 200 OK
Response body:

{
    "accountStatus": {
        "isDisabled": false,
        "isLocked": false,
        "expirationDate": null
    },
    "passwordStatus": {
        "whenChanged": "2020-07-14T16:27:49.5590448Z",
        "expirationStatus": 0,
        "expirationDate": "2020-08-09T16:27:49.5590448Z"
    },
    "guid": "7a4267ce-d354-44e7-8bd6-c681f1284a41",
    "dn": "CN=John Smith,CN=Users,DC=example,DC=com",
    "displayName": "John Smith",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "properties": {}
}
 Example 2: Retrieve a user with photo and department

The following code sample retrieves a user object with their photo and department. The photo is returned as a Base64-encoded string.

Request

PowerShell
$userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"
$propertiesToGet = "department,thumbnailPhoto"

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects" 
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestParams = @{
    directoryObject = $userIdentifier;
    properties = $propertiesToGet;
}

# Make request
Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
C#
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com";
        const string propertiesToGet = "department,thumbnailPhoto";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";

        UriBuilder requestUrl = new UriBuilder(
            "https://host.example.com/restApi/api/directoryObjects");
        requestUrl.Query += $"?directoryObject={userIdentifier}";
        requestUrl.Query += $"&properties={propertiesToGet}";

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
            client.DefaultRequestHeaders.Add("Adm-Authorization", token);

            // Make request
            string response = await client.GetStringAsync(requestUrl.ToString());
            Console.WriteLine(response);
        }
    }
}
cURL
curl  --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--get -X GET 'https://host.example.com/restApi/api/directoryObjects' \
--data-urlencode 'directoryobject=CN=John Smith,CN=Users,DC=example,DC=com' \
--data-urlencode 'properties=department,thumbnailphoto'
node.js
var userIdentifier = encodeURIComponent("CN=John Smith,CN=Users,DC=example,DC=com");
var propertiesToGet = "department,thumbnailPhoto";

var https = require("https");

// Request parameters and headers
var requestPath = "/restApi/api/directoryObjects"
    + `?directoryobject=${userIdentifier}`
    + `&properties=${propertiesToGet}`;

// Request parameters and headers
var options = {
    'method': 'GET',
    'hostname': 'host.example.com',
    'path': requestPath,
    'headers': {
        "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD",
    }
};

// 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.end();

Response

HTTP Status code: 200 OK
Response body:

{
    "accountStatus": {
        "isDisabled": false,
        "isLocked": false,
        "expirationDate": null
    },
    "passwordStatus": {
        "whenChanged": "2020-07-14T16:27:49.5590448Z",
        "expirationStatus": 0,
        "expirationDate": "2020-08-09T16:27:49.5590448Z"
    },
    "guid": "7a4267ce-d354-44e7-8bd6-c681f1284a41",
    "dn": "CN=John Smith,CN=Users,DC=example,DC=com",
    "displayName": "John Smith",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "properties": {
        "department": [ "Marketing" ],
        "thumbnailPhoto": [
        "iVBORw0KGgoAAAANSUhEUgAAAEAAAABACAYAAACqaXHeAAAAA
        XNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAAAJcEhZcwAADsM
        AAA7DAcdvqGQAAAvWSURBVHhe7ZsJcJXVFceZdgadqVaZqRapI
        lVQKKBF1GppFcSNVrGtS4vUWu1icRw7tbZ1WGRH9q2swbBHVhF
        BUUCWkD0h+x5CCFlJQhKyhyycnt9978IzhDxe+nAgvP/Mm/e9m
        +99797/Pefe8z/nptOZM2de19fKq/XVSUQ26+uqBRaw0nl9VcJ
        HgI8AHwHtJyCtuEYSCqul+nSTs8U98irqZUVkgdQ1Njtb3KOmo
        Vn89DuFVaedLd5DuwgIya6QAQui5Iczw+X26WHyfECS8y/uEZ5
        TKYP9YuVUXaOzxT1O6MB/vjxWEk9Um8+QAZHegMcEHDlZK9eND
        5J3Pss0HSuvbZT4wiqp1VnK1L81NJ8x9+VqB0uqG8z1sbI6M4t
        HS+vMfTmn6qXpjOM+EFtQZf7miiL9bmRuhZTWOIjiO6ebzkjY8
        QrpPDZQrShf0ktqJUufbVGllkj/PIHHBLy984jcv+iw89M5JBf
        VyPenhkh2uaNDv1idIGP3ZAnj7D03Qh77ME6eWZMon6WelF6zw
        01nGfTDS2LkJ0ui5a7ZEfLO55nmu2tjTshA/Y2haikLQ/OkXt3
        lDrW2sJwKeeOTdLl2XKD8eGGUTD1wXO6YFS5JTst4a8cRGbkpx
        VxfLDwm4HH/OP2hDOenc0hSAr43OfgsAU+vipfRu7PMdZdJQfL
        +3mNm9oOOnZIffBBqLOJZJeS3HyULtpChM/cdtaxwHeRTK+Nlm
        L6sjRSrNdwyLVSi8iqlvqlZblW3wxLAo0rS5P3Z5rrP3Ej5KrP
        MXF8sPCbg95tS5bEVcc5P54AFdJ0WIgWVDt8cvjZRxqgFNKsJ0
        OHD2nkQrh2/fUaYFFY2mNn7PO2kaQcDdFaXRxRIhpr2kOUxMlD
        XmS8zSqVGrcU+wxKAe4B1sSfkCf94CdXnPqBWw+95Ao8JOKQz2........",
        ]
    }
}
 Example 3: Retrieve a group, its owner, and its members

The following code sample retrieves a group object and the distinguished names (DNs) of its owner and members using the optional properties parameter in the request.

Request

PowerShell
$groupIdentifier = "CN=My Group,OU=Groups,DC=example,DC=com"
$propertiesToGet = "member,managedBy"

$baseUrl = "https://host.example.com/restApi"
$endpoint = "/api/directoryObjects"  
$requestUrl = $baseUrl + $endpoint
$requestHeaders = @{"Adm-Authorization" = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD"}
$requestParams = @{
    directoryObject = $groupIdentifier;
    properties = $propertiesToGet
}
 
# Make request
Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $requestParams
C#
using System;
using System.Net.Http;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        const string groupIdentifier = "CN=My Group,OU=Groups,DC=example,DC=com";
        const string propertiesToGet = "member,managedBy";
        const string token = "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD";
        
        UriBuilder requestUrl = new UriBuilder(
            "https://host.example.com/restApi/api/directoryObjects");
        requestUrl.Query += $"?directoryObject={groupIdentifier}";
        requestUrl.Query += $"&properties={propertiesToGet}";

        // Initialize HTTP client
        using (HttpClient client = new HttpClient())
        {
           client.DefaultRequestHeaders.Add("Adm-Authorization", token);

            // Make request
            string response = await client.GetStringAsync(requestUrl.ToString());
            Console.WriteLine(response);
        }
    }
}
cURL
curl  --header 'Adm-Authorization: HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD' \
--get -X GET 'https://host.example.com/restApi/api/directoryObjects' \
--data-urlencode 'directoryobject=CN=My Group,OU=Groups,DC=example,DC=com' \
--data-urlencode 'properties=member,managedBy'
node.js
var groupIdentifier = encodeURIComponent("CN=My Group,OU=Groups,DC=example,DC=com");
var propertiesToGet = "member,managedBy";

var https = require("https");

// Request parameters and headers
var requestPath = "/restApi/api/directoryObjects"
    + `?directoryobject=${groupIdentifier}`
    + `&properties=${propertiesToGet}`;

var options = {
    'method': 'GET',
    'hostname': 'host.example.com',
    'path': requestPath,
    'headers': {
        "Adm-Authorization": "HxtdAPz73OFfae7....w7lQvxjJHIbVqgkCtPtLD",
    }
};

// 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.end();

Response

HTTP Status code: 200 OK
Response body:

{
    "groupType": 1,
    "groupScope": 2,
    "membershipType": 0,
    "guid": "a7b63270-b8a4-4c34-b830-7e0d09f2e021",
    "dn": "CN=My Group,OU=Groups,DC=example,DC=com",
    "displayName": "My Group",
    "objectType": "group",
    "objectTypeCode": 3,
    "domainName": "example.com",
    "properties": {
        "managedby": [
            "CN=John Smith,CN=Users,DC=example,DC=com"
        ],
        "member": [
            "CN=John Smith,CN=Users,DC=example,DC=com",
            "CN=Richard Magnus,OU=Users,DC=example,DC=com",
            "CN=Ella Parkes,OU=Users,DC=example,DC=com"
        ]
    }
}

See also