---
title: "Get Employees Directory"
method: GET
path: "/api/v1/employees/directory"
tags: ["Employees", "Public API"]
---

# Get Employees Directory

`GET /api/v1/employees/directory`

Returns the company's published employee directory: a fieldset definition plus an array of employee records whose keys match the field ids. Coverage is intentionally incomplete — companies can hide individual employees (commonly contractors) from the directory, and those employees are silently absent from the response with no indicator that they exist. The fieldset is also fixed by company directory configuration; callers cannot request additional fields. Use this endpoint only when you specifically want the company's curated directory subset (for example, an org-style listing that respects the company's directory settings). For complete or general-purpose employee listings, batch lookups by ID, or filtering by name/status, use **List Employees** (`list-employees`) instead. For tabular reporting, custom field selection, or analytical queries across many employees, use **Get Data from Dataset (v2)** (`get-data-from-dataset-v2`) instead. Response format follows the `Accept` header: `application/json` returns a JSON object with `fields` and `employees` arrays; `application/xml` (the default when `Accept` is missing or any non-JSON value) returns a `<directory>` document with `<fieldset>` and `<employees>` children. Employee `id` values are internal employee IDs returned as strings in both formats. The response shape varies by caller permission and per-company configuration: when neither company-wide directory sharing nor org-chart sharing is enabled the endpoint returns 403; when only org-chart sharing is enabled the response uses a reduced fieldset (limited to the fields exposed by the org chart); when the resulting directory has no employees the endpoint returns 404 rather than an empty list.

OAuth Scopes: employee_directory

## Query parameters

- `onlyCurrent` boolean

## Headers

- `AcceptHeaderParameter` 'application/xml' | 'application/json'

## Response `200`

Directory fieldset and matching employee records, encoded per the `Accept` header.

- object
  - `fields` object[] — Field definitions included in this response. Each entry describes one key that appears on every employee object. The set of fields is fixed by company directory configuration; the `canUploadPhoto` entry is always appended.
    - `id` string — Field identifier; appears as a key on each employee object.
    - `type` string — Field data type. Observed values include `text`, `list`, `email`, `bool`, `url`, and `employee`.
    - `name` string — Human-readable field label.
  - `employees` object[] — One object per directory employee. Every object includes `id` (internal employee ID as a string) and `canUploadPhoto` (1 if the authenticated caller may upload a photo for this employee, 0 otherwise), plus one key per entry in `fields`. The exact key set varies with company directory configuration. Field values are returned in the JSON type indicated by the matching `fields[].type` (for example, `bool` fields are JSON booleans).

## Other responses

- `401` — Unauthorized.
- `403` — The authenticated user's company has neither company-wide directory sharing nor org-chart sharing enabled, so no directory is available.
- `404` — The resulting directory is empty (no employees matched the filter for this company configuration).
- `500` — Internal server error.

---

[API](https://skmtc.net/bamboohr/apis/bamboohr-api.md) · [All operations](https://skmtc.net/bamboohr/apis/bamboohr-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/bamboohr/bamboohr-api/revisions/19ebf391a399/schema)