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. You can use:
Distinguished name (DN)
# Example CN=John Smith,CN=Users,DC=example,DC=comGlobally unique identifier (GUID)
# Example 7a4267ce-d354-44e7-8bd6-c681f1284a41Security identifier (SID)
# Example S-1-5-21-3635565734-1729062999-1822655016-1627 - 
properties - 
False
 - 
string
 - 
A comma-separated list of 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
- guid
 - dn
 - displayName
 - objectType
 - objectTypeCode
 - domainName
 - directoryType
 
 
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
 - 
$baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects" # Request parameters $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN} $queryParams = @{"directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com"} # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams - C#
 - 
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string baseUrl = "https://host.example.com"; const string endpoint = "/restApi/api/directoryObjects"; // Request parameters const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"; UriBuilder requestUrl = new() { Host = baseUrl + endpoint, Query = $"?directoryObject={userIdentifier}" }; // Initialize HTTP client using HttpClient client = new(); client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } - cURL
 - 
curl --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \ --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 https = require('https'); // Request parameters var userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"; var requestPath = "/restApi/api/directoryObjects" + `?directoryobject=${userIdentifier}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': encodeURI(requestPath), 'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'} }; // 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.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} queryParams = {"directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com"} # Make request request = requests.get(requestUrl, headers=requestHeaders, params=queryParams) response = json.loads(request.content) print(response) 
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",
    "directoryType": 1,
    "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
 - 
$baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects" # Request parameters $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN} $queryParams = @{ "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com"; "properties" = "department,thumbnailPhoto" } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams - C#
 - 
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string baseUrl = "https://host.example.com"; const string endpoint = "/restApi/api/directoryObjects"; // Request parameters const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"; const string propertiesToGet = "department,thumbnailPhoto"; UriBuilder requestUrl = new() { Host = baseUrl + endpoint, Query = $"?directoryObject={userIdentifier}" + $"&properties={propertiesToGet}" }; // Initialize HTTP client using HttpClient client = new(); client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } - cURL
 - 
curl --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \ --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 https = require('https'); // Request parameters var userIdentifier = encodeURIComponent("CN=John Smith,CN=Users,DC=example,DC=com"); var propertiesToGet = "department,thumbnailPhoto"; var requestPath = "/restApi/api/directoryObjects" + `?directoryobject=${userIdentifier}` + `&properties=${propertiesToGet}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'} }; // 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.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} queryParams = { "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com", "properties": "department,thumbnailPhoto" } # Make request request = requests.get(requestUrl, headers=requestHeaders, params=queryParams) response = json.loads(request.content) print(response) 
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",
    "directoryType": 1,
    "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 user with Adaxes custom attributes
The following code sample retrieves a user object with the values of the following Adaxes custom attributes:
- Custom boolean attribute (adm-CustomAttributeBoolean1)
 - Custom date attribute (adm-CustomAttributeDate1)
 - Custom DN syntax attribute (adm-CustomAttributeObject1)
 
Adaxes custom attributes are retrieved just like any other attributes.
Request
- PowerShell
 - 
$baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects" # Request parameters $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN} $queryParams = @{ "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com"; "properties" = "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1" } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams - C#
 - 
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string baseUrl = "https://host.example.com"; const string endpoint = "/restApi/api/directoryObjects"; // Request parameters const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"; const string propertiesToGet = "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1"; UriBuilder requestUrl = new() { Host = baseUrl + endpoint, Query = $"?directoryObject={userIdentifier}" + $"&properties={propertiesToGet}" }; // Initialize HTTP client using HttpClient client = new(); client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } - cURL
 - 
curl --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \ --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=adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1' - node.js
 - 
var https = require('https'); // Request parameters var userIdentifier = encodeURIComponent("CN=John Smith,CN=Users,DC=example,DC=com"); var propertiesToGet = "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1"; var requestPath = "/restApi/api/directoryObjects" + `?directoryobject=${userIdentifier}` + `&properties=${propertiesToGet}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'} }; // 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.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} queryParams = { "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com", "properties": "adm-CustomAttributeBoolean1,adm-CustomAttributeDate1,adm-CustomAttributeObject1" } # Make request request = requests.get(requestUrl, headers=requestHeaders, params=queryParams) response = json.loads(request.content) print(response) 
Response
HTTP Status code: 200 OK
Response body:
{
    "accountStatus": {
        "isDisabled": false,
        "isLocked": false,
        "expirationDate": null
    },
    "passwordStatus": {
        "whenChanged": null,
        "expirationStatus": 2,
        "expirationDate": null
    },
    "guid": "1d6fcc50-ab32-4419-bf67-9ac6b5dfc3be",
    "dn": "CN=John Doe,CN=Users,DC=example,DC=com",
    "displayName": "John Doe",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "directoryType": 1,
    "properties": {
        "adm-CustomAttributeBoolean1": [ true ],
        "adm-CustomAttributeDate1": [ "2021-11-27T10:00:00Z" ],
        "adm-CustomAttributeObject1": [ "CN=My Group,OU=Groups,DC=example,DC=com" ]
    }
}
Example 4 – Retrieve a group, its owners, and its members
The following code sample retrieves a group object and the distinguished names (DNs) of all its owners and members using the optional properties parameter in the request.
Request
- PowerShell
 - 
$baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects" # Request parameters $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN} $queryParams = @{ "directoryObject" = "CN=My Group,OU=Groups,DC=example,DC=com"; "properties" = "member,adm-Owners" } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams - C#
 - 
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string baseUrl = "https://host.example.com"; const string endpoint = "/restApi/api/directoryObjects"; // Request parameters const string groupIdentifier = "CN=My Group,OU=Groups,DC=example,DC=com"; const string propertiesToGet = "member,adm-Owners"; UriBuilder requestUrl = new() { Host = baseUrl + endpoint, Query = $"?directoryObject={groupIdentifier}" + $"&properties={propertiesToGet}" }; // Initialize HTTP client using HttpClient client = new(); client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } - cURL
 - 
curl --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \ --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,adm-Owners' - node.js
 - 
var https = require('https'); // Request parameters var groupIdentifier = encodeURIComponent("CN=My Group,OU=Groups,DC=example,DC=com"); var propertiesToGet = "member,adm-Owners"; var requestPath = "/restApi/api/directoryObjects" + `?directoryobject=${groupIdentifier}` + `&properties=${propertiesToGet}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'} }; // 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.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} queryParams = { "directoryObject": "CN=My Group,OU=Groups,DC=example,DC=com", "properties": "member,adm-Owners" } # Make request request = requests.get(requestUrl, headers=requestHeaders, params=queryParams) response = json.loads(request.content) print(response) 
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",
    "directoryType": 1,
    "properties": {
        "managedby": [
            "CN=John Smith,CN=Users,DC=example,DC=com",
            "CN=Anna Singer,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"
        ]
    }
}
Example 5 – Retrieve a user and their Microsoft 365 properties
The following code sample retrieves a user object and the following properties of their Microsoft 365 account:
- Usage location (adm-O365AccountLocation)
 - Sign-in status (adm-O365AccountBlocked)
 - Assigned licenses (adm-O365AccountLicenses)
 
Request
- PowerShell
 - 
$baseUrl = "https://host.example.com/restApi" $endpoint = "/api/directoryObjects" # Request parameters $requestUrl = $baseUrl + $endpoint $requestHeaders = @{"Adm-Authorization" = YOUR-SECURITY-TOKEN} $queryParams = @{ "directoryObject" = "CN=John Smith,CN=Users,DC=example,DC=com"; "properties" = "adm-O365AccountLocation,adm-O365AccountBlocked,adm-O365AccountLicenses" } # Make request Invoke-RestMethod -Method GET -Headers $requestHeaders -Uri $requestUrl -Body $queryParams - C#
 - 
using System; using System.Net.Http; using System.Threading.Tasks; class Program { static async Task Main() { const string baseUrl = "https://host.example.com"; const string endpoint = "/restApi/api/directoryObjects"; // Request parameters const string userIdentifier = "CN=John Smith,CN=Users,DC=example,DC=com"; const string propertiesToGet = "adm-O365AccountLocation,adm-O365AccountBlocked,adm-O365AccountLicenses"; UriBuilder requestUrl = new() { Host = baseUrl + endpoint, Query = $"?directoryObject={userIdentifier}" + $"&properties={propertiesToGet}" }; // Initialize HTTP client using HttpClient client = new(); client.DefaultRequestHeaders.Add("Adm-Authorization", YOUR-SECURITY-TOKEN); // Make request string response = await client.GetStringAsync(requestUrl.ToString()); Console.WriteLine(response); } } - cURL
 - 
curl --header 'Adm-Authorization: YOUR-SECURITY-TOKEN' \ --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=adm-O365AccountLocation,adm-O365AccountBlocked,adm-O365AccountLicenses' - node.js
 - 
var https = require('https'); // Request parameters var userIdentifier = encodeURIComponent("CN=John Smith,CN=Users,DC=example,DC=com"); var propertiesToGet = "adm-O365AccountLocation,adm-O365AccountBlocked,adm-O365AccountLicenses"; var requestPath = "/restApi/api/directoryObjects" + `?directoryobject=${userIdentifier}` + `&properties=${propertiesToGet}`; var options = { 'method': 'GET', 'hostname': 'host.example.com', 'path': requestPath, 'headers': {'Adm-Authorization': 'YOUR-SECURITY-TOKEN'} }; // 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.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} queryParams = { "directoryObject": "CN=John Smith,CN=Users,DC=example,DC=com", "properties": "adm-O365AccountLocation,adm-O365AccountBlocked,adm-O365AccountLicenses" } # Make request request = requests.get(requestUrl, headers=requestHeaders, params=queryParams) response = json.loads(request.content) print(response) 
Response
HTTP Status code: 200 OK
Response body:
{
    "accountStatus": {
        "isDisabled": false,
        "isLocked": false,
        "expirationDate": null
    },
    "passwordStatus": {
        "whenChanged": null,
        "expirationStatus": 2,
        "expirationDate": null
    },
    "guid": "1d6fcc50-ab32-4419-bf67-9ac6b5dfc3be",
    "dn": "CN=John Doe,CN=Users,DC=example,DC=com",
    "displayName": "John Doe",
    "objectType": "user",
    "objectTypeCode": 2,
    "domainName": "example.com",
    "directoryType": 1,
    "properties": {
        "adm-O365AccountLocation": [ "US" ],
        "adm-O365AccountBlocked": [ false ],
        "adm-O365AccountLicenses": [
            {
                "licenses": [ "M365_F1" ],
                "apps": [
                    "AAD_PREMIUM",
                    "RMS_S_PREMIUM",
                    "EXCHANGE_S_FOUNDATION",
                    "MFA_PREMIUM",
                    "TEAMS1"
                ]
            }
        ]
    }
}