Search Directory

Searches the directory for entities (users, groups, or applications) matching a prefix string, based on the organization ID.

API Endpoint

GET {accessURL}/{organizationName}/identity_/api/Directory/Search/{partitionGlobalId}

Replace {accessURL} in all endpoint paths with the base URL for your cloud platform:

Cloud platform	Access URL
Test Cloud	https://cloud.uipath.com/
Test Cloud Public Sector	https://govcloud.uipath.us/
Test Cloud Dedicated	https://{customURL}.dedicated.uipath.com/

Scopes

Requires the following scopes:

• PM.Directory

Request Headers

--header 'Authorization: Bearer {access_token}'\
--header 'Content-Type: application/json'

note

To obtain the {access_token}, make sure to authenticate through one of the methods described here.

Path Parameters

Path param	Data type	Description
partitionGlobalId (required)	String (GUID)	The ID of the organization to search within.

Query Parameters

Query param	Data type	Description
startsWith (required)	String	The prefix string to search for. Results will match entities whose name, email, or display name starts with this value.
entityType (optional)	String	The type of directory entity to search for. Valid values: User, Group, Application. Cannot be used together with sourceFilter.
sourceFilter (optional)	Array of strings	Filters results by source. Valid values: LocalUsers, DirectoryUsers, LocalGroups, DirectoryGroups, RobotAccounts, Applications. Cannot be used together with entityType.
scope (optional)	String	Optional scope used for entities in active directory.

Responses

200 OK

Returns a list of directory entities matching the search criteria.

[
    {
        "source": "aad",
        "identifier": "aad|a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "identityName": "john.doe@example.com",
        "displayName": "John Doe",
        "email": "john.doe@example.com",
        "type": "User",
        "objectType": "DirectoryUser"
    },
    {
        "source": "aad",
        "identifier": "aad|b2c3d4e5-f6a7-8901-bcde-f12345678901",
        "identityName": "Engineering Team",
        "displayName": "Engineering Team",
        "email": null,
        "type": "Group",
        "objectType": "DirectoryGroup"
    }
]

400 Bad Request

Returned when both entityType and sourceFilter are provided, or when required parameters are missing.

Example Request

Let's say you gathered all the information needed to build the API call.

• Your {baseURL} is: https://cloud.uipath.com/{organizationName}/identity_
• Your {access_token} is: 1234 (for length considerations).
• The {partitionGlobalId} is: 3fa85f64-5717-4562-b3fc-2c963f66afa6
• You want to search for users whose name starts with "john".

The call should resemble the following example (cURL):

curl --location --request GET 'https://cloud.uipath.com/{organizationName}/identity_/api/Directory/Search/3fa85f64-5717-4562-b3fc-2c963f66afa6?startsWith=john&entityType=User' \
--header 'Authorization: Bearer 1234' \
--header 'Content-Type: application/json'

Here's the response body for a successful call:

[
    {
        "source": "aad",
        "identifier": "aad|a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "identityName": "john.doe@example.com",
        "displayName": "John Doe",
        "email": "john.doe@example.com",
        "type": "User",
        "objectType": "DirectoryUser"
    }
]