BambooHR Toolkit

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.

attention

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

1. Generate a BambooHR API key

   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.

2. Open an agent or workflow

   Open an agent and add the BambooHR toolkit under Toolkits, or add a BambooHR step to a workflow.

3. Create a saved connection

   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.

4. Enable only the tools you need

   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.

5. Test with a safe read action

   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.