> ## Documentation Index
> Fetch the complete documentation index at: https://ai-kb.automationanywhere.com/llms.txt
> Use this file to discover all available pages before exploring further.
# BambooHR Toolkit
> Connect BambooHR to agents and workflows to look up employees, managers, PTO balances, and who is out.
The BambooHR toolkit connects a BambooHR company account to agents and workflows using an API key and lets you look up employees and org structure, check who is out of office, list and manage time-off requests, check PTO balances, and run company reports. Authentication uses a personal BambooHR API key that inherits the creating user's permissions.
## Prerequisites
* An active BambooHR account in the target company.
* Permission in BambooHR to view the employees, time-off records, and reports the agent or workflow requires.
* A personal BambooHR API key — go to **My Info → API Keys** in BambooHR, generate a key, and copy it immediately.
* The company subdomain from your BambooHR login URL. For `https://acme.bamboohr.com`, the subdomain is `acme` only — not the full URL.
BambooHR API keys inherit the full permissions of the user who created them — use a dedicated, least-privilege user rather than an administrator account. Write actions (Add Employee, Update Employee, Add Time Off Request, Update Time Off Status) are confirmation-gated and should only be enabled for approved workflows. Never paste API keys into tickets, chat, prompts, screenshots, or documentation.
## Setup
Sign in to BambooHR as the dedicated user. Go to **My Info → API Keys**, generate a personal API key, and copy it immediately. Note the company subdomain from the login URL.
Open an agent and add the **BambooHR** toolkit under Toolkits, or add a BambooHR step to a workflow.
In the BambooHR step, choose **+ New** under Select saved connection. Enter a **Connection Name**, the **Company Subdomain** (letters, digits, and hyphens only — not the full URL), and the **API Key**. Save the connection.
Start with read-only actions: **Find Employee**, **Who's Out**, and **Get Time Off Balances**. Enable write actions only after access and confirmation policy are approved.
Run **Who's Out** without any date inputs to confirm the connection. An empty list is a valid result when nobody is out.
## Available tools
### Employees
| Tool | Description |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Find Employee** | Searches the company directory by name or work email. Returns matching candidates — does not guess when multiple people match. |
| **Get Employee Directory** | Lists employees with an optional department filter. Returns up to 250 employees — use Find Employee for large companies. |
| **Get Employee** | Returns one employee's fields including title, department, manager, hire date, and employment status. |
| **Get Employee Tables** | Returns tabular history for one employee — job information, employment status, compensation, contacts, or emergency contacts. |
| **Get Meta Fields** | Lists BambooHR field definitions. Use a query filter to narrow results before using fields in Get Employee or reports. |
| **Add Employee** | Creates a new employee. Confirmation-gated. For approved provisioning workflows only. |
| **Update Employee** | Updates fields on an existing employee by exact employee ID. Confirmation-gated. |
### Time Off
| Tool | Description |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| **Who's Out** | Lists people out of office (time off or holidays) in a date range. Safe first test — read-only with no required inputs. |
| **List Time Off Requests** | Lists time-off requests between two dates, optionally filtered by employee and status. |
| **Get Time Off Types** | Lists time-off types and default hours. Run this before Add Time Off Request to get the type ID. |
| **Get Time Off Balances** | Returns an employee's PTO balances as of a date. |
| **Add Time Off Request** | Creates a time-off request for an employee. Confirmation-gated. |
| **Update Time Off Status** | Approves, denies, or cancels an existing time-off request. Confirmation-gated. |
### Reports
| Tool | Description |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **Get Company Report** | Fetches a saved company report by its ID as JSON. |
| **Get Custom Report** | Runs an ad-hoc report for a specified list of field identifiers. Use Get Meta Fields to discover field IDs first. |
### Advanced
| Tool | Description |
| ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| **Custom API Call** | Calls an arbitrary BambooHR v1 endpoint. Use only when no dedicated tool covers the need. POST, PUT, PATCH, and DELETE can change HR data. |
## Use cases
* Answer "who is out this week?" by running Who's Out with the current week's date range.
* Look up an employee by name or email and return their manager, title, and department.
* Check an employee's remaining PTO balance before submitting a time-off request on their behalf.
* Run a custom report to pull a specific set of employee fields for a downstream workflow step.
* List pending time-off requests in a date range and summarize them for a manager.
## Troubleshooting
| Symptom | Likely cause | Fix |
| ------------------------------------------ | --------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| BambooHR not visible in the toolkit picker | The toolkit is not enabled for the environment or project. | Ask a Super Admin to enable and show the toolkit, then refresh the picker. |
| Invalid subdomain error | The full URL, trailing slash, or extra characters were entered. | Enter only the company name from the BambooHR URL — letters, digits, and hyphens only. |
| `401 Unauthorized` | The API key is missing, revoked, or mistyped. | Generate a new personal key in BambooHR and update the saved connection. |
| `403 Forbidden` or sparse employee fields | The API key's user cannot see those records or fields. | Use a BambooHR user account with the required access level. Sparse fields usually indicate a permission limit, not missing HR data. |
| No employee matched or multiple matches | The name or email matched zero or more than one person. | Use a work email for a precise lookup, or present the candidates and ask which person to use. |
| Directory looks truncated | The directory returns up to 250 employees client-side. | Use **Find Employee** to look up a specific person instead of listing the full directory. |
| `429 Too Many Requests` | BambooHR rate-limited the company. | The toolkit retries up to three times with backoff. Reduce concurrent steps and retry after a short wait. |
| Write action did not run | Confirmation was required and not approved. | Approve the confirmation card. If writes are not in scope, keep those tools disabled. |