At a glance
- Availability: Experimental (how to enable).
- Auth: Basic auth.
- Connection: HTTP Basic auth with
BAMBOOHR_API_KEYas the username andBAMBOOHR_API_PASSWORDas the password. - Docs: https://documentation.bamboohr.com/docs/getting-started
Credentials
Set these per environment. See Connect an integration.| Variable | Required | Description |
|---|---|---|
BAMBOOHR_API_KEY | Yes | BambooHR API key, used as the HTTP Basic username. Generate it from your name menu in BambooHR under API Keys. Docs. |
BAMBOOHR_API_PASSWORD | No | HTTP Basic password. BambooHR ignores the value - any string works; the conventional value is x. Docs. |
BAMBOOHR_SUBDOMAIN | Yes | Your BambooHR company subdomain - the {company} part of https://{company}.bamboohr.com. Pass it as the companyDomain parameter on each tool. Docs. |
Setup
- Get a BambooHR account: Use your company’s existing BambooHR account, or start a free trial at https://www.bamboohr.com to get a test company. Note your subdomain - the {company} part of https://{company}.bamboohr.com.
- Generate an API key: Log in to BambooHR, click your name in the lower-left corner, and choose API Keys to generate a key. The key inherits the permissions of your user, so time-off and directory access depend on what your user can see.
- Store the credentials: Add BAMBOOHR_API_KEY=<your key> and BAMBOOHR_SUBDOMAIN=<your subdomain> to your .env file. The API uses HTTP Basic auth with the API key as the username and any string as the password (BAMBOOHR_API_PASSWORD defaults to x).
- Verify access: Run the Get Employee Directory tool with companyDomain set to your subdomain. Requests go to https://{companyDomain}.bamboohr.com/api/v1/.
- Responses default to XML; every tool sends Accept: application/json to get JSON
- List Time-Off Requests requires both start and end dates (YYYY-MM-DD)
- Whether you can create or approve time-off requests depends on the permissions of the user who owns the API key
Tools
| Tool | Access | Description |
|---|---|---|
| Get Employee Directory | Read | Get the company employee directory with names, job titles, departments, and contact details |
| Get Employee | Read | Get a single employee record with the specific fields you request |
| List Time-Off Requests | Read | List time-off requests that overlap a date range, optionally filtered by employee or status |
| Create Time-Off Request | Write | Create a time-off request for an employee; it must be approved before it appears in history |
| List Time-Off Types | Read | List the company’s time-off types and their IDs - needed to fill the timeOffTypeId field when creating a time-off request |
| Update Time-Off Request Status | Write | Approve, deny, or cancel an existing time-off request (the API user must have approval permissions) |
| List Field Metadata | Read | List all employee fields available in the account (standard and custom) so agents know which field names Get Employee accepts |
| List Who’s Out | Read | List approved time off and company holidays in a date range to see who is out of office |
Example prompts
- Check BambooHR for who is out of office this week and summarize by team.
- Find an employee I name in the BambooHR directory and show their job title, department, and contact details.
- List BambooHR time-off requests with status requested for the next month and summarize what needs approval.