--- updatedAt: 2026-04-20T19:45:37.000Z agentTools: projectIndex: https://documentation.bamboohr.com/llms.txt --- # Get Employees Directory 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 `` document with `
` and `` 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 ### Avoid this common pitfall The Company Directory is a feature that can be managed and even disabled by each company in their account settings. Because of this, calling this endpoint may perform differently or not at all (if the feature is disabled) from one company to the next. Instead, we recommend integrators use the request a custom report API to retrieve bulk employee data. Sample Response ```json JSON { "fields": [ { "id": "displayName", "type": "text", "name": "Display Name" }, { "id": "firstName", "type": "text", "name": "First Name" }, { "id": "lastName", "type": "text", "name": "Last Name" }, { "id": "gender", "type": "text", "name": "Gender" }, { "id": "jobTitle", "type": "list", "name": "Job Title" }, { "id": "workPhone", "type": "text", "name": "Work Phone" }, { "id": "workPhoneExtension", "type": "text", "name": "Work Extension" }, { "id": "skypeUsername", "type": "text", "name": "Skype Username" }, { "id": "facebook", "type": "text", "name": "Facebook URL" } ], "employees": [ { "id":123, "displayName":"John Doe", "firstName":"John", "lastName":"Doe", "gender":"Male", "jobTitle":"Customer Service Representative", "workPhone":"555-555-5555", "workPhoneExtension":null, "skypeUsername":"JohnDoe", "facebook":"JohnDoeFacebook" } ] } ``` ```xml
Display name First name Last name Gender Job title Work Phone Work Extension Skype Username Facebook URL
John Doe John Doe Male Customer Service Representative 555-555-5555 JohnDoe JohnDoeFacebook ``` # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "BambooHR API", "description": "BambooHR API documentation. https://documentation.bamboohr.com/", "version": "1.0" }, "servers": [ { "url": "https://{companyDomain}.bamboohr.com", "variables": { "companyDomain": { "default": "companySubDomain", "description": "Company domain" } } } ], "paths": { "/api/v1/employees/directory": { "get": { "tags": [ "Employees", "Public API" ], "summary": "Get Employees Directory", "description": "Returns the company's published employee directory: a fieldset definition plus an array of employee records whose keys match the field ids.\n\n**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).\n\n**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.\n\n**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.\n\n**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.\n\n**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.\n\n**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 `` document with `
` and `` 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.\n\nOAuth Scopes: employee_directory", "operationId": "get-employees-directory", "parameters": [ { "$ref": "#/components/parameters/AcceptHeaderParameter" }, { "name": "onlyCurrent", "in": "query", "description": "When true (the default), only employees whose hire date and employment-status effective date are on or before today are returned. Set to false to also include employees with a future hire date or future employment-status effective date (typically pre-boarding hires). The fieldset is unaffected.", "required": false, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Directory fieldset and matching employee records, encoded per the `Accept` header.", "content": { "application/json": { "schema": { "title": "EmployeesDirectoryJsonResponse", "properties": { "fields": { "description": "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.", "type": "array", "items": { "properties": { "id": { "description": "Field identifier; appears as a key on each employee object.", "type": "string" }, "type": { "description": "Field data type. Observed values include `text`, `list`, `email`, `bool`, `url`, and `employee`.", "type": "string" }, "name": { "description": "Human-readable field label.", "type": "string" } }, "type": "object" } }, "employees": { "description": "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).", "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "type": "object" } }, "application/xml": { "schema": { "title": "EmployeesDirectoryXmlResponse", "properties": { "fieldset": { "description": "Field definitions included in this response.", "properties": { "field": { "type": "array", "items": { "properties": { "id": { "description": "Field identifier; matches the `id` attribute on each `` element inside ``.", "type": "string", "xml": { "attribute": true } }, "value": { "description": "Human-readable field label, serialized as the element's text content.", "type": "string" } }, "type": "object" } } }, "type": "object" }, "employees": { "description": "Directory employee records.", "properties": { "employee": { "type": "array", "items": { "properties": { "id": { "description": "Internal employee ID, serialized as an attribute on the `` element.", "type": "string", "xml": { "attribute": true } }, "field": { "description": "Field values for the employee. Each `` element has an `id` attribute matching one of the `
` ids and the value as element text. Currency fields additionally carry a `currency` attribute (ISO currency code). Boolean fields are serialized as the strings `true`/`false`; the appended `canUploadPhoto` field is serialized as `yes`/`no`.", "type": "array", "items": { "properties": { "id": { "description": "Field identifier matching one of the ids in `
`.", "type": "string", "xml": { "attribute": true } }, "value": { "description": "Field value serialized as element text content.", "type": "string" } }, "type": "object" } } }, "type": "object" } } }, "type": "object" } }, "type": "object", "xml": { "name": "directory" } } } } }, "401": { "description": "Unauthorized." }, "403": { "description": "The caller has neither usable Company Directory nor Company Org Chart access, so no directory is available. This can mean the features are disabled company-wide (Settings > Company Directory) or that they are not shared with the caller's access level; the response does not distinguish those cases. When both company toggles are off, every caller including administrators receives this response. The body is empty and the diagnostic reason is carried in the `x-bamboohr-error-message` header.", "headers": { "x-bamboohr-error-message": { "description": "Diagnostic reason for the 403 response, for example `Directory disabled for this account`.", "schema": { "type": "string", "example": "Directory disabled for this account" } } } }, "404": { "description": "The resulting directory is empty for this company configuration and `onlyCurrent` setting, so no employee records are returned." }, "500": { "description": "Internal server error." } }, "security": [ { "basic": [] }, { "oauth": [ "employee_directory" ] } ] } } }, "components": { "schemas": { "CompanyIntegrationsUpdatedWebhookPayload": { "title": "Company Integrations Updated Webhook Payload", "description": "Webhook payload sent when company integrations are updated.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "company-integrations.updated" ], "example": "company-integrations.updated" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing company information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" } }, "type": "object" } }, "type": "object" }, "CompanyUpdatedWebhookPayload": { "title": "Company Updated Webhook Payload", "description": "Webhook payload sent when a company is updated.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "company.updated" ], "example": "company.updated" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing company information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" } }, "type": "object" } }, "type": "object" }, "CompanyDeletedWebhookPayload": { "title": "Company Deleted Webhook Payload", "description": "Webhook payload sent when a company is deleted.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "company.deleted" ], "example": "company.deleted" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing company information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" } }, "type": "object" } }, "type": "object" }, "EmployeeCreatedWebhookPayload": { "title": "Employee Created Webhook Payload", "description": "Webhook payload sent when a new employee is created.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "employee.created" ], "example": "employee.created" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing employee information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" }, "employeeId": { "description": "The employee ID that was created", "type": "string", "example": "100" } }, "type": "object" } }, "type": "object" }, "EmployeeDeletedWebhookPayload": { "title": "Employee Deleted Webhook Payload", "description": "Webhook payload sent when an employee is deleted.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "employee.deleted" ], "example": "employee.deleted" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing employee information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" }, "employeeId": { "description": "The employee ID that was deleted", "type": "string", "example": "100" } }, "type": "object" } }, "type": "object" }, "EmployeeUpdatedWebhookPayload": { "title": "Employee Updated Webhook Payload", "description": "Webhook payload sent when an employee is updated.", "properties": { "type": { "description": "The event type identifier", "type": "string", "enum": [ "employee.updated" ], "example": "employee.updated" }, "timestamp": { "description": "ISO 8601 timestamp (UTC) when the event was fired", "type": "string", "format": "date-time", "example": "2025-02-18T15:30:00Z" }, "data": { "description": "Event data containing employee and change information", "properties": { "companyId": { "description": "The company ID", "type": "string", "example": "12345" }, "employeeId": { "description": "The employee ID that was updated", "type": "string", "example": "100" }, "changedFields": { "description": "Array of API aliases for fields that changed and are monitored by this webhook", "type": "array", "items": { "type": "string" }, "example": [ "firstName", "lastName", "department" ] } }, "type": "object" } }, "type": "object" } }, "responses": { "WebhookSuccessResponse": { "description": "Webhook received successfully (200-299 status code)." }, "WebhookClientErrorResponse": { "description": "Client error (400-499 status code) - the webhook endpoint intentionally rejected the request. BambooHR will not retry webhooks that return 4xx status codes." }, "WebhookServerErrorResponse": { "description": "Server error (500+ status code). BambooHR will automatically retry this webhook up to 5 times using exponential backoff (5min, 10min, 20min, 40min, 80min intervals)." } }, "parameters": { "AcceptHeaderParameter": { "name": "AcceptHeaderParameter", "in": "header", "description": "This endpoint can produce either JSON or XML.", "schema": { "type": "string", "enum": [ "application/xml", "application/json" ] } } }, "securitySchemes": { "oauth": { "type": "oauth2", "description": "OAuth 2.0 authentication", "flows": { "authorizationCode": { "authorizationUrl": "/authorize.php", "tokenUrl": "/token.php", "scopes": { "access_level": "View and manage User Access Levels", "access_level.write": "View and manage User Access Levels", "benchmarking:compensation": "Compensation Benchmarking", "compensation_benchmarks": "Read and write access to compensation benchmarking data including job-location pairs, benchmark values, and benchmark sources.", "compensation_benchmarks.write": "Read and write access to compensation benchmarking data including job-location pairs, benchmark values, and benchmark sources.", "pay_grades_and_bands": "Read access to levels and bands data including compensation level groups, levels, pay bands, and job title assignments.", "pay_grades_and_bands.write": "Read access to levels and bands data including compensation level groups, levels, pay bands, and job title assignments.", "planning_cycles": "Read access to compensation planning cycle data including cycle lists, details, summaries, employees, budgets, approvals, admins, and change communication settings.", "planning_cycles.write": "Read access to compensation planning cycle data including cycle lists, details, summaries, employees, budgets, approvals, admins, and change communication settings.", "background_checks": "Access background check information", "background_checks.write": "Access background check information", "benefit": "Get Benefit Details", "benefit.write": "Get Benefit Details", "company_file": "Company Files", "company_file.write": "Company Files", "company:info": "Company Info", "company:details": "Access to comprehensive company information including profile fields, metadata, and configuration settings", "company:details.write": "Access to comprehensive company information including profile fields, metadata, and configuration settings", "customer_onboarding": "Customer Onboarding workflows and setup", "customer_onboarding.write": "Customer Onboarding workflows and setup", "company:administration": "Company Administration", "company:administration.write": "Company Administration", "data_cleaner": "Allows viewing data cleaning job data.", "data_cleaner.write": "Allows viewing data cleaning job data.", "data_hygiene": "Read access to data hygiene findings.", "data_hygiene.write": "Read access to data hygiene findings.", "hr_benchmarks": "Read access to HR benchmarking topics and company-vs-benchmark data.", "deductions": "Access to employee deductions information", "deductions.write": "Access to employee deductions information", "payroll": "Allows access to payroll related fields", "payroll.write": "Allows access to payroll related fields", "payroll:beneficial_owners": "Access to beneficial ownership certification information for payroll compliance, including business structure, exemption status, and individual beneficial owner details with personal information and ownership percentages", "payroll:beneficial_owners.write": "Access to beneficial ownership certification information for payroll compliance, including business structure, exemption status, and individual beneficial owner details with personal information and ownership percentages", "payroll:legal_entities": "Access to payroll legal entities information, including FEIN and legal entity details", "payroll:retirements": "Access to employee payroll retirements information", "payroll:pay_schedules": "Access to payroll pay schedule information", "payroll:pay_periods": "Access to payroll pay period information", "payroll:earnings": "Access to earnings records within a pay cycle", "payroll:pay_cycles": "Access to pay cycle records", "payroll:pay_stubs": "Access to employee pay stub information including gross pay, net pay, deductions, taxes, and YTD totals", "payroll:pay_stubs.write": "Access to employee pay stub information including gross pay, net pay, deductions, taxes, and YTD totals", "payroll:payrolls": "Access to payroll information including pay dates and processing details", "payroll:ach_returns": "Access to ACH return information including return details and resolution", "payroll:ach_returns.write": "Access to ACH return information including return details and resolution", "payroll:tipped_occupations": "Access to Treasury Tipped Occupation Codes and the codes assigned to each job title, used to report Box 14b on employee W-2s", "payroll:tipped_occupations.write": "Access to Treasury Tipped Occupation Codes and the codes assigned to each job title, used to report Box 14b on employee W-2s", "esignature:instance": "Access eSignature instance data and signing workflows, including viewing instances, completing signing steps, and managing user signatures.", "esignature:instance.write": "Access eSignature instance data and signing workflows, including viewing instances, completing signing steps, and managing user signatures.", "employee:assets": "Assets Assigned to Employee", "employee:assets.write": "Assets Assigned to Employee", "employee:emergency_contacts": "Employee Contacts and Emergency Contacts", "employee:emergency_contacts.write": "Employee Contacts and Emergency Contacts", "employee:vaccination": "Employee COVID-19 Data", "employee:vaccination.write": "Employee COVID-19 Data", "employee:custom_fields": "Employee Custom Fields", "employee:custom_fields.write": "Employee Custom Fields", "employee:custom_fields_encrypted": "Employee Encrypted Custom Fields", "employee:custom_fields_encrypted.write": "Employee Encrypted Custom Fields", "employee:demographic": "Includes Employee Ethnicity and Nationality", "employee:demographic.write": "Includes Employee Ethnicity and Nationality", "employee:dependent": "Employee Dependent Information", "employee:dependent.write": "Employee Dependent Information", "employee:dependent:ssn": "Employee Dependent SSN/SIN", "employee:dependent:ssn.write": "Employee Dependent SSN/SIN", "employee:education": "Employee Education Information", "employee:education.write": "Employee Education Information", "employee:contact": "Employee Contact", "employee:contact.write": "Employee Contact", "employee:identification": "Employee Identification", "employee:identification.write": "Employee Identification", "employee:job": "Employee Job Information", "employee:job.write": "Employee Job Information", "employee:management": "Manage Employees", "employee:management.write": "Manage Employees", "employee:photo": "Employee Photo", "employee:photo.write": "Employee Photo", "employee": "All non-sensitive employee-related information", "employee.write": "All non-sensitive employee-related information", "employee:name": "Includes Any Employee Name Details", "employee:name.write": "Includes Any Employee Name Details", "employee_directory": "Employee Directory", "employee:file": "Employee Files", "employee:file.write": "Employee Files", "employee:compensation": "Employee Payroll Information", "employee:compensation.write": "Employee Payroll Information", "employee:providers": "Allows access to employee provider information", "employee:providers.write": "Allows access to employee provider information", "employee:providers:payroll": "Allows access to employee payroll provider information", "employee:providers:payroll.write": "Allows access to employee payroll provider information", "employee:tabs": "View and manage custom employee tabs.", "employee:tabs.write": "View and manage custom employee tabs.", "sensitive_employee:protected_info": "Employee SSN, SIN, Birthday", "sensitive_employee:protected_info.write": "Employee SSN, SIN, Birthday", "sensitive_employee:address": "Includes Any Employee Address Details", "sensitive_employee:address.write": "Includes Any Employee Address Details", "sensitive_employee:creditcards": "Credit Cards Assigned to Employee", "sensitive_employee:creditcards.write": "Credit Cards Assigned to Employee", "employee:payroll.write": "Employee Payroll Information", "ask_bamboohr:chat_messages": "Read and write chat messages in Ask BambooHR on behalf of the authenticated user", "ask_bamboohr:chat_messages.write": "Read and write chat messages in Ask BambooHR on behalf of the authenticated user", "ask_bamboohr:settings": "View and manage Ask BambooHR feature settings", "ask_bamboohr:settings.write": "View and manage Ask BambooHR feature settings", "ask_bamboohr:policy_documents": "View and manage policy documents used as sources in Ask BambooHR", "ask_bamboohr:policy_documents.write": "View and manage policy documents used as sources in Ask BambooHR", "equity": "Read access to company-level equity settings such as calculation type, valuation, share counts, pricing, and vesting-related configuration.", "equity.write": "Read access to company-level equity settings such as calculation type, valuation, share counts, pricing, and vesting-related configuration.", "field": "Query Lists of Fields, Tables and Lists.", "field.write": "Query Lists of Fields, Tables and Lists.", "goal": "Access performance goals data for employees.", "goal.write": "Access performance goals data for employees.", "performance:assessments": "Access performance assessment data for employees", "performance:assessments.write": "Access performance assessment data for employees", "performance:feedback": "Access performance feedback data for employees", "performance:feedback.write": "Access performance feedback data for employees", "performance:settings": "Access and manage performance management configurations", "performance:settings.write": "Access and manage performance management configurations", "performance:one_on_ones": "Access one on one meeting data for employees", "performance:one_on_ones.write": "Access one on one meeting data for employees", "enps:settings": "View and manage eNPS feature settings", "enps:settings.write": "View and manage eNPS feature settings", "employee_wellbeing:settings": "View and manage Employee Wellbeing feature settings", "employee_wellbeing:settings.write": "View and manage Employee Wellbeing feature settings", "global_employment": "Allows access to data and workflows for Employer of Record (EOR) employees and contractors managed in Remote.", "global_employment.write": "Allows access to data and workflows for Employer of Record (EOR) employees and contractors managed in Remote.", "job_organization": "Manage job organization, including job profiles", "job_organization.write": "Manage job organization, including job profiles", "hiring:job_openings": "Access and manage job openings, pipelines, rules, questions, collaborators, and job board postings", "hiring:job_openings.write": "Access and manage job openings, pipelines, rules, questions, collaborators, and job board postings", "hiring:applications": "Access and manage applications, candidates, interviews, and candidate emails", "hiring:applications.write": "Access and manage applications, candidates, interviews, and candidate emails", "hiring:offers": "Access and manage offers, offer terms, and offer letters", "hiring:offers.write": "Access and manage offers, offer terms, and offer letters", "hiring:checkr": "Access and manage Checkr background checks for candidates", "hiring:checkr.write": "Access and manage Checkr background checks for candidates", "hiring:talent_pools": "Access and manage talent pools, pool candidates, and pool collaborators", "hiring:talent_pools.write": "Access and manage talent pools, pool candidates, and pool collaborators", "hiring:settings": "Access and manage hiring configuration including statuses, candidate sources, and email and offer letter templates", "hiring:settings.write": "Access and manage hiring configuration including statuses, candidate sources, and email and offer letter templates", "offline_access": "Allows the application to reauthenticate to BambooHR with a refresh token", "openid": "Allows the application to authenticate with BambooHR", "recognitions:manage": "Access and manage Rewards and Recognition settings, exclusion rules, and point allocations, and view Rewards and Recognition reports for the company", "recognitions:manage.write": "Access and manage Rewards and Recognition settings, exclusion rules, and point allocations, and view Rewards and Recognition reports for the company", "recognitions:suggestions": "Read and write recognition suggestions for employees, including viewer suggestion pools and one-off or broadcast suggestion writes", "recognitions:suggestions.write": "Read and write recognition suggestions for employees, including viewer suggestion pools and one-off or broadcast suggestion writes", "report": "Allows access to query custom reports and creation of bulk data requests", "report.write": "Allows access to query custom reports and creation of bulk data requests", "tasks": "Manage Employee Tasks", "tasks.write": "Manage Employee Tasks", "calendar:events": "View company calendar events.", "holidays": "View and manage company holidays and view the global holiday catalog.", "holidays.write": "View and manage company holidays and view the global holiday catalog.", "time_off": "Employee Time Off Information", "time_off.write": "Employee Time Off Information", "time_off:requests": "View and manage employee time off requests, including submitting, approving, and denying them.", "time_off:requests.write": "View and manage employee time off requests, including submitting, approving, and denying them.", "time_off:categories": "View and manage time off categories, the types of time off a company offers.", "time_off:categories.write": "View and manage time off categories, the types of time off a company offers.", "time_off:policies": "View and manage time off policies, the rules that control how employees accrue and use time off.", "time_off:policies.write": "View and manage time off policies, the rules that control how employees accrue and use time off.", "time_tracking": "Add and Manage Hours Worked.", "time_tracking.write": "Add and Manage Hours Worked.", "time_tracking:breaks": "View and manage meal and rest break tracking information.", "time_tracking:breaks.write": "View and manage meal and rest break tracking information.", "time_tracking:shift_differentials": "View and manage time tracking shift differentials.", "time_tracking:shift_differentials.write": "View and manage time tracking shift differentials.", "time_tracking:kiosks": "View and manage time tracking kiosks.", "time_tracking:kiosks.write": "View and manage time tracking kiosks.", "time_tracking:time_clocks": "View and manage time tracking time clocks.", "time_tracking:time_clocks.write": "View and manage time tracking time clocks.", "time_tracking:timesheets": "View and manage time tracking timesheets.", "time_tracking:timesheets.write": "View and manage time tracking timesheets.", "time_tracking:project": "View and manage time tracking projects and tasks.", "time_tracking:project.write": "View and manage time tracking projects and tasks.", "time_tracking:configurations": "View and manage time tracking configurations.", "time_tracking:configurations.write": "View and manage time tracking configurations.", "time_tracking:employees": "View and manage employee time tracking enrollment.", "time_tracking:employees.write": "View and manage employee time tracking enrollment.", "time_tracking:imports": "View and manage time tracking imports.", "time_tracking:imports.write": "View and manage time tracking imports.", "scheduling:schedules": "View and manage schedules.", "scheduling:schedules.write": "View and manage schedules.", "scheduling:shifts": "View and manage shifts within schedules.", "scheduling:shifts.write": "View and manage shifts within schedules.", "training": "Get Training Details", "training.write": "Get Training Details", "total_rewards": "Read and write access to Total Rewards data including employee statements, onboarding steps, and custom disclaimers.", "total_rewards.write": "Read and write access to Total Rewards data including employee statements, onboarding steps, and custom disclaimers.", "user": "Get Users List", "user.write": "Get Users List", "user:management": "Manage state of company users", "user:management.write": "Manage state of company users", "webhooks": "Create and Manage Application Specific Webhooks", "webhooks.write": "Create and Manage Application Specific Webhooks", "workflows:external_tasks": "View and manage workflow external tasks.", "workflows:external_tasks.write": "View and manage workflow external tasks.", "workflows:instances": "View and manage workflow instances.", "workflows:instances.write": "View and manage workflow instances.", "workflows:triggers": "View and manage automation triggers.", "workflows:triggers.write": "View and manage automation triggers.", "error_management": "Manage errors and notifications", "error_management.write": "Manage errors and notifications", "public.integration": "Allows access to all authorized scopes for all employees. Must be installed by an admin.", "public.user": "Authorizes the application to perform scoped actions on behalf of the user who authorized the application.", "alerts": "Provides read and write access to alert configurations.", "alerts.write": "Provides read and write access to alert configurations.", "approval_workflows": "Provides read and write access to approval workflow configurations.", "approval_workflows.write": "Provides read and write access to approval workflow configurations.", "compensation_tools": "Read access to the list of available compensation tools and upsell information for the company.", "employee_verifications": "Provides read and write access to employee verification records, including I-9 and E-Verify verification data and partner role assignments.", "employee_verifications.write": "Provides read and write access to employee verification records, including I-9 and E-Verify verification data and partner role assignments.", "esignature": "Provides read access to electronic signature records and requests.", "onboarding": "Provides read access to employee new hire paperwork and onboarding records.", "onboarding.write": "Provides read access to employee new hire paperwork and onboarding records.", "gridlets": "Gridlets", "gridlets.write": "Gridlets", "meta": "Read-only access to public BambooHR meta reference endpoints such as countries, subdivisions, timezones, currencies, and related lookup data used to configure integrations.", "mcp": "Grants access to Model Context Protocol (MCP) endpoints", "insights": "Insight data", "insights.write": "Insight data", "marketplace:catalog": "Read marketplace catalog data, including app categories and solutions.", "marketplace:data_sources": "Read marketplace data source identity, including whether a source is BambooHR or a partner integration." } } } }, "basic": { "type": "http", "scheme": "basic" } } }, "tags": [ { "name": "Employees", "description": "Create, retrieve, and update core employee records." }, { "name": "Webhook Events", "description": "Browse the catalog of available webhook event types." }, { "name": "Public API", "description": "Public API" } ], "webhooks": { "company-integrations.updated": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Company Integrations Updated", "description": "\nTriggered when company integrations are updated.\n\n### Behavior & Constraints\n- **Permission Checking**: This event does **not** enforce permission checking. The webhook will fire for all subscribers regardless of the API token's permissions.\n- **Event Scope**: This event fires when any integration settings are modified for the company, including enabling, disabling, or updating integration configurations.\n", "operationId": "company-integrations-updated-webhook", "requestBody": { "description": "Webhook payload containing company integration update information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyIntegrationsUpdatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } }, "company.updated": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Company Updated", "description": "\nTriggered when company information or company status changes.\n\n### Behavior & Constraints\n- This event is emitted for general company updates.\n- When the underlying change is a company status change, the emitted event depends on the new status:\n - If the new status is `DELETED` or `CANCELLED`, the system emits `company.deleted` instead.\n - Otherwise the system emits `company.updated`.\n", "operationId": "company-updated-webhook", "requestBody": { "description": "Webhook payload containing information about the company update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyUpdatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "grease-monkeys" } }, "company.deleted": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Company Deleted", "description": "\nTriggered when a company status change results in the company being considered deleted/closed.\n\n### Behavior & Constraints\n- This event is emitted when the new company status is `DELETED` or `CANCELLED`.\n- For other company updates and status changes, the system emits `company.updated`.\n", "operationId": "company-deleted-webhook", "requestBody": { "description": "Webhook payload containing information about the company deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompanyDeletedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "grease-monkeys" } }, "employee.created": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Employee Created", "description": "\nTriggered when a new employee is created.\n\n### Behavior & Constraints\n- **Creation Sequence**: When an employee is created, both `employee.created` and `employee.updated` events fire sequentially due to the create-then-initialize pattern.\n- **Data Availability**: The `data` object contains the `companyId` and `employeeId` of the newly created employee.\n- **Permission Checking**: This event does **not** enforce permission checking. The webhook will fire for all subscribers regardless of the API token's field-level permissions.\n\n### Deprecation Notice\n**Note:** This event is the modern replacement for the legacy `employee_with_fields.created` event. While the legacy event is deprecated, it will remain available for the foreseeable future to support existing integrations. We encourage using this new event for all new development.\n\n**Important:** You cannot subscribe to both this new event and the legacy `employee_with_fields` events on the same webhook. Webhooks created without specifying any events will default to the legacy behavior, effectively subscribing to the `employee_with_fields` events automatically.\n", "operationId": "employee-created-webhook", "requestBody": { "description": "Webhook payload containing information about the employee creation", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeCreatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } }, "employee.deleted": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Employee Deleted", "description": "\nTriggered when an employee is deleted.\n\n### Behavior & Constraints\n- **Permission Checking**: This event does **not** enforce permission checking. The webhook will fire for all subscribers regardless of the API token's field-level permissions.\n\n### Deprecation Notice\n**Note:** This event is the modern replacement for the legacy `employee_with_fields.deleted` event. While the legacy event is deprecated, it will remain available for the foreseeable future to support existing integrations. We encourage using this new event for all new development.\n\n**Important:** You cannot subscribe to both this new event and the legacy `employee_with_fields` events on the same webhook. Webhooks created without specifying any events will default to the legacy behavior, effectively subscribing to the `employee_with_fields` events automatically.\n", "operationId": "employee-deleted-webhook", "requestBody": { "description": "Webhook payload containing information about the employee deletion", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeDeletedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } }, "employee.updated": { "post": { "tags": [ "Webhook Events", "Public API" ], "summary": "Employee Updated", "description": "\nTriggered when an employee record is updated and at least one of the monitored fields has changed.\n\n### Behavior & Constraints\n- **Monitoring**: At least one `monitorField` is required when subscribing to this event via `POST /api/v1/webhooks`.\n- **Permissions**: For API-created webhooks, this event will not fire if the webhook creator lacks access to all monitored fields being changed.\n\n### Detailed Description\n- **Creation Sequence**: When an employee is created, both `employee.created` and `employee.updated` events fire sequentially due to the create-then-initialize pattern.\n- **Field Consolidation**: When multiple fields change simultaneously, they may be consolidated into a single event. Currently, custom field updates and standard field updates are grouped separately and may fire as two events.\n- **Effective Dates**: For history-tracked fields (e.g., `jobTitle`, `payRate`), events fire only when changes take effect, not when future-dated changes are created.\n- **Changed Fields**: The `changedFields` array contains the API aliases for fields that changed and are monitored by this webhook. Aliases match those returned by `GET /api/v1/webhooks/monitor_fields`.\n\n### Deprecation Notice\n**Note:** This event is the modern replacement for the legacy `employee_with_fields.updated` event. While the legacy event is deprecated, it will remain available for the foreseeable future to support existing integrations. We encourage using this new event for all new development.\n\n**Important:** You cannot subscribe to both this new event and the legacy `employee_with_fields` events on the same webhook. Webhooks created without specifying any events will default to the legacy behavior, effectively subscribing to the `employee_with_fields` events automatically.\n", "operationId": "employee-updated-webhook", "requestBody": { "description": "Webhook payload containing information about the employee update", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmployeeUpdatedWebhookPayload" } } } }, "responses": { "200": { "$ref": "#/components/responses/WebhookSuccessResponse" }, "400": { "$ref": "#/components/responses/WebhookClientErrorResponse" }, "500": { "$ref": "#/components/responses/WebhookServerErrorResponse" } }, "x-team-name": "plat-api" } } }, "x-tagGroups": [ { "name": "Account Information", "tags": [ "Account Information" ] }, { "name": "Alerts", "tags": [ "Alerts" ] }, { "name": "Applicant Tracking", "tags": [ "Applicant Tracking" ] }, { "name": "Benefits", "tags": [ "Benefits" ] }, { "name": "Change Tracking", "tags": [ "Change Tracking" ] }, { "name": "Company Details", "tags": [ "Company", "Company Profile" ] }, { "name": "Compensation", "tags": [ "Compensation", "Compensation Benchmarking", "Compensation Planning", "Pay Grades & Bands", "Total Rewards" ] }, { "name": "Custom Fields", "tags": [ "Custom Fields" ] }, { "name": "Datasets and Reporting", "tags": [ "Custom Reports", "Datasets", "Reports" ] }, { "name": "Employee Details", "tags": [ "Employees", "Photos" ] }, { "name": "Employee Tables", "tags": [ "Employee Tables" ] }, { "name": "Employee Verification", "tags": [ "Employee Verification" ] }, { "name": "Field Metadata", "tags": [ "Field Metadata" ] }, { "name": "Files", "tags": [ "Company Files", "Employee Files" ] }, { "name": "Goals", "tags": [ "Goals" ] }, { "name": "Holidays", "tags": [ "Holidays" ] }, { "name": "Hours", "tags": [ "Hours" ] }, { "name": "Locations", "tags": [ "Locations" ] }, { "name": "Login", "tags": [ "Login" ] }, { "name": "Onboarding", "tags": [ "Onboarding" ] }, { "name": "Scheduling", "tags": [ "Scheduling" ] }, { "name": "Time Off", "tags": [ "Time Off" ] }, { "name": "Time Tracking", "tags": [ "Time Tracking", "Meal & Rest Breaks" ] }, { "name": "Training", "tags": [ "Training" ] }, { "name": "Webhooks", "tags": [ "Webhooks", "Webhook Events" ] } ] } ```