# Search Directory

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

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](https://docs.uipath.com/test-cloud/automation-cloud/latest/api-guide/authentication-methods#authentication-methods).
:::

## 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.

```json
[
    {
        "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:

```json
[
    {
        "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"
    }
]
```