Returns the company's published employee directory: a fieldset definition plus an array of employee records whose keys match the field ids.

When to use this endpoint. Use it for basic, non-sensitive information about coworkers who appear in the company's published directory, especially coworkers the caller does not manage. For the authenticated caller's own record, use Get Employee (get-employee) with the id 0 instead. It answers questions such as who a coworker is, their job title, department, division, or location, how to reach them at work, and who they report to. When the company shares its full directory, every record includes supervisor, which makes this the most direct way to answer org chart and reporting structure questions such as who reports to a given manager. Do not assume that field is present: always read the fields array in the response to see what a given company actually exposes, because a company that shares only its org chart returns a reduced fieldset that omits supervisor (see Coverage and limits below).

Access. Directory access is governed by the company's Company Directory and Company Org Chart sharing settings (Settings > Company Directory in the BambooHR web app), together with whether those features are shared with the caller's access level. It is not governed by per-employee record permissions, so when the directory is shared with the caller the employee data is not narrowed to the people whose records they can otherwise read, and an employee with no managerial or administrative access can normally read the full directory. The canUploadPhoto value remains caller-specific.

Fields returned. The fieldset is fixed by company directory configuration and callers cannot request additional fields. The fields array in each response lists exactly which fields that company exposes, so treat it as authoritative rather than assuming a fixed set. With full directory sharing it covers names, job title, department, division, location, manager (supervisor), work email, work and mobile phone, pronouns, social profile links, and photo information. It never includes compensation, national identifiers such as SSN, birth date, home address, home contact details, or employment status and history, in any configuration.

Coverage and limits. This endpoint returns the whole directory in one response and accepts no name, department, or field filters, so narrow the results on the client side. Companies choose which employees appear in the directory, and anyone excluded is absent with no indicator that they exist. Inactive and former employees are also excluded, so an administrator researching someone who has left the company will not find them here even though the record still exists; use get-employee or list-employees for those. Absence from this response therefore means the employee is not in the published directory, not that no such employee exists, so do not conclude from this endpoint alone that someone does not work at the company. For the same reason it is not an authoritative roster; prefer list-employees or get-data-from-dataset-v2 when completeness matters.

Related endpoints. To read fields this endpoint does not expose, or to select arbitrary fields for a single employee, use Get Employee (get-employee), passing the id 0 for the authenticated caller's own record. For a coworker name, department, or location lookup, retrieve this directory and narrow the employees array on the client side rather than filtering elsewhere. Use List Employees (list-employees) for roster, pagination, sorting, or batch-by-id workflows where the caller can read the relevant fields, and Get Data from Dataset (v2) (get-data-from-dataset-v2) for tabular reporting, custom field selection, or analytical queries across many employees. Those endpoints apply stricter, endpoint-specific permissions and may return 403, null or omitted field values, or filtered-out rows; this endpoint is the appropriate choice for general coworker and org chart lookups.

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 also varies with per-company configuration, where Company Directory sharing takes precedence: when it is enabled the full fieldset is returned whether or not Company Org Chart sharing is also on. When the caller has neither usable Company Directory nor Company Org Chart access the endpoint returns 403 with an empty body and the header x-bamboohr-error-message: Directory disabled for this account. That can mean the features are disabled company-wide or that they are not shared with the caller's access level, and the response does not distinguish those cases; when both company toggles are off, every caller including administrators receives it. When only org-chart sharing is available (Company Directory off, Company Org Chart on) the response still lists every directory employee but uses a reduced fieldset, observed as displayName, firstName, lastName, preferredName, jobTitle, pronouns, and the photo fields, which means supervisor, department, division, location, work email, and phone numbers are all absent and reporting-structure or work-contact questions cannot be answered from that configuration; when the resulting directory has no employees the endpoint returns 404 rather than an empty list.

OAuth Scopes: employee_directory