<!-- llms.txt: https://workos.com/llms.txt -->

# Directory

A directory stores information about an organization's employee management system.

Synchronizing with a directory enables you to receive changes to an organization's [user](https://workos.com/docs/reference/directory-sync/directory-user) and [group](https://workos.com/docs/reference/directory-sync/directory-group) structure.

Directory providers vary in implementation details and may require different sets of fields for integration, such as API keys, subdomains, endpoints, usernames, etc. Where available, the WorkOS API will provide these fields when fetching directory records.

## Delete a Directory

Permanently deletes an existing directory. It cannot be undone.

:::code-group{title="Request"}

```bash language="curl"
curl --request DELETE \
  --url https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74 \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

await workos.directorySync.deleteDirectory(
  'directory_01ECAZ4NV9QMV47GW873HDCX74',
);
```

```rb language="ruby"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.directory_sync.delete_directory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74")
```

```py language="python"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.directory_sync.delete_directory(id_="directory_01ECAZ4NV9QMV47GW873HDCX74")
```

```go language="go"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.DirectorySync().Delete(context.Background(), "directory_01ECAZ4NV9QMV47GW873HDCX74")
	if err != nil {
		panic(err)
	}
}
```

```php language="php"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->directorySync()
    ->deleteDirectory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74");
```

```java language="java"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.directorySync.deleteDirectory("directory_01ECAZ4NV9QMV47GW873HDCX74");
```

```cs language="dotnet"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.DirectorySync.DeleteAsync("directory_01ECAZ4NV9QMV47GW873HDCX74");
```

```rust language="rust"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .directory_sync()
        .delete_directory("directory_01ECAZ4NV9QMV47GW873HDCX74")
        .await?;

    Ok(())
}
```

:::

## Get a Directory

Get the details of an existing directory.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/directories/directory_01ECAZ4NV9QMV47GW873HDCX74" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const directory = await workos.directorySync.getDirectory(
  'directory_01ECAZ4NV9QMV47GW873HDCX74',
);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.directory_sync.get_directory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74")
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.directory_sync.get_directory(id_="directory_01ECAZ4NV9QMV47GW873HDCX74")
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.DirectorySync().Get(context.Background(), "directory_01ECAZ4NV9QMV47GW873HDCX74")
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos
    ->directorySync()
    ->getDirectory(id: "directory_01ECAZ4NV9QMV47GW873HDCX74");
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.directorySync.getDirectory("directory_01ECAZ4NV9QMV47GW873HDCX74");
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.DirectorySync.GetAsync("directory_01ECAZ4NV9QMV47GW873HDCX74");
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .directory_sync()
        .get_directory("directory_01ECAZ4NV9QMV47GW873HDCX74")
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "directory",
  "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
  "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
  "external_key": "sPa12dwRQ",
  "type": "gsuite directory",
  "state": "linked",
  "name": "Foo Corp",
  "domain": "foo-corp.com",
  "metadata": {
    "users": {
      "active": 42,
      "inactive": 3
    },
    "groups": 5
  },
  "created_at": "2026-01-15T12:00:00.000Z",
  "updated_at": "2026-01-15T12:00:00.000Z"
}
```

:::

## List Directories

Get a list of all of your existing directories matching the criteria specified.

:::code-group

```bash language="curl" title="Request" tab="1"
curl "https://api.workos.com/directories" \
  --header "Authorization: Bearer sk_example_123456789"
```

```js language="js" title="Request" tab="1"
import { WorkOS } from '@workos-inc/node';

const workos = new WorkOS('sk_example_123456789');

const directoryList = await workos.directorySync.listDirectories();

console.log(directoryList.data);
```

```rb language="ruby" title="Request" tab="1"
require "workos"

WorkOS.configure do |config|
  config.api_key = "sk_example_123456789"
end

WorkOS.client.directory_sync.list_directories
```

```py language="python" title="Request" tab="1"
from workos import WorkOSClient

client = WorkOSClient(api_key="sk_example_123456789", client_id="client_123456789")

client.directory_sync.list_directories()
```

```go language="go" title="Request" tab="1"
package main

import (
	"context"

	"github.com/workos/workos-go/v10"
)

func main() {
	client := workos.NewClient("sk_example_123456789")

	_, err := client.DirectorySync().List(context.Background())
	if err != nil {
		panic(err)
	}
}
```

```php language="php" title="Request" tab="1"
<?php

use WorkOS\WorkOS;

$workos = new WorkOS(
    apiKey: "sk_example_123456789",
    clientId: "client_123456789",
);

$workos->directorySync()->listDirectories();
```

```java language="java" title="Request" tab="1"
import com.workos.WorkOS;

WorkOS workos = new WorkOS("sk_example_123456789");

workos.directorySync.listDirectories();
```

```cs language="dotnet" title="Request" tab="1"
using WorkOS;

var client = new WorkOSClient(new WorkOSOptions {
    ApiKey = "sk_example_123456789",
    ClientId = "client_123456789",
});

await client.DirectorySync.ListAsync();
```

```rust language="rust" title="Request" tab="1"
use workos::Client;

#[tokio::main]
async fn main() -> Result<(), workos::Error> {
    let client = Client::builder()
        .api_key("sk_example_123456789")
        .client_id("client_123456789")
        .build();

    let _result = client
        .directory_sync()
        .list_directories()
        .await?;

    Ok(())
}
```

```json language="json" title="Response" tab="2"
{
  "object": "list",
  "data": [
    {
      "object": "directory",
      "id": "directory_01ECAZ4NV9QMV47GW873HDCX74",
      "organization_id": "org_01EHZNVPK3SFK441A1RGBFSHRT",
      "external_key": "sPa12dwRQ",
      "type": "gsuite directory",
      "state": "linked",
      "name": "Foo Corp",
      "domain": "foo-corp.com",
      "metadata": {
        "users": {
          "active": 42,
          "inactive": 3
        },
        "groups": 5
      },
      "created_at": "2026-01-15T12:00:00.000Z",
      "updated_at": "2026-01-15T12:00:00.000Z"
    }
  ],
  "list_metadata": {
    "before": "directory_01HXYZ123456789ABCDEFGHIJ",
    "after": "directory_01HXYZ987654321KJIHGFEDCBA"
  }
}
```

:::

### directory

| Field | Type | Required | Description |
| --- | --- | --- | --- |
| `object` | "directory" | Yes | Distinguishes the Directory object. |
| `id` | string | Yes | Unique identifier for the Directory. |
| `organization_id` | string | Yes | The unique identifier for the Organization in which the directory resides. |
| `external_key` | string | Yes | External Key for the Directory. |
| `type` | "azure scim v2.0" \| "bamboohr" \| "breathe hr" \| ... | Yes | The type of external Directory Provider integrated with. |
| `state` | "linked" \| "validating" \| "invalid_credentials" \| "unlinked" \| "deleting" | Yes | Describes whether the Directory has been successfully connected to an external provider. |
| `name` | string | Yes | The name of the directory. |
| `domain` | string | No | The URL associated with an Enterprise Client. |
| `metadata` | object | No | Aggregate counts of directory users and groups synced from the provider. |
| `created_at` | string | Yes | The timestamp when the Directory was created. |
| `updated_at` | string | Yes | The timestamp when the Directory was last updated. |

### DELETE /directories/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier for the Directory. |

### GET /directories/{id}

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `id` | string | Yes | Unique identifier for the Directory. |

#### Returns

| Field | Type | Description |
| --- | --- | --- |
| `directory` | object | Distinguishes the Directory object. |

### GET /directories

#### Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `before` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. |
| `after` | string | No | An object ID that defines your place in the list. When the ID is not present, you are at the end of the list. |
| `limit` | integer | No | Upper limit on the number of objects to return, between `1` and `100`. Defaults to `10`. |
| `order` | "normal" \| "desc" \| "asc" | No | Order the results by the creation time. Defaults to `normal`. |
| `organization_id` | string | No | Filter Directories by their associated organization. |
| `search` | string | No | Searchable text to match against Directory names. |
| `domain` | string | No | Filter Directories by their associated domain. |