BambooHR Time Off & Employee Directory
Who is out today, and who asked for leave next week? Reads BambooHR's Who's Out calendar and time off requests, looks people up in the employee directory, estimates future balances per policy, and files or approves leave requests for a manager.
Connect this API to an AI agent Browse all specs
What you can do with BambooHR Time Off & Employee Directory via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /{companyDomain}/v1/employees/directory |
listEmployeeDirectory | List employees in the company directory |
| GET | /{companyDomain}/v1/employees/{id}/ |
getEmployee | Get chosen fields for one employee (use 0 for yourself) |
| GET | /{companyDomain}/v1/time_off/whos_out/ |
listWhosOut | List who is out (time off and holidays) in a date range |
| GET | /{companyDomain}/v1/time_off/requests/ |
listTimeOffRequests | List time off requests in a date range |
| GET | /{companyDomain}/v1/meta/time_off/types/ |
listTimeOffTypes | List time off types (vacation, sick, ...) |
| GET | /{companyDomain}/v1/meta/time_off/policies/ |
listTimeOffPolicies | List time off policies |
| GET | /{companyDomain}/v1_1/employees/{employeeId}/time_off/policies |
listEmployeeTimeOffPolicies | List the time off policies assigned to an employee |
| GET | /{companyDomain}/v1/employees/{employeeId}/time_off/calculator |
estimateTimeOffBalance | Estimate an employee's time off balances on a future date |
| PUT | /{companyDomain}/v1/employees/{employeeId}/time_off/request |
requestTimeOff | Create a time off request for an employee |
| PUT | /{companyDomain}/v1/time_off/requests/{requestId}/status |
changeTimeOffRequestStatus | Approve, deny or cancel a time off request |
Authentication
basic
HTTP Basic
HTTP basic auth: your BambooHR API key as the username and any text (for example x) as the password.
How to get a credential
- Sign in to BambooHR (https://<company>.bamboohr.com).
- Click your profile picture (top right) and choose API Keys. If the menu item is missing, ask an admin to give your access level API access.
- Click Add New Key, name it (e.g.
VX Agents) and copy the key; it is shown only once. - Note your company subdomain (the
<company>part of the URL); every call needs it ascompanyDomain.
Permissions used
The key acts as the user who created it, with that user's BambooHR access level.
| Access needed | Operations |
|---|---|
| View the directory / employee fields | listEmployeeDirectory, getEmployee |
| View time off (own, reports or all) | listWhosOut, listTimeOffRequests, listTimeOffTypes, listTimeOffPolicies, listEmployeeTimeOffPolicies, estimateTimeOffBalance |
| Request time off for that employee | requestTimeOff |
| Approve time off for that employee | changeTimeOffRequestStatus |
Common errors
- 401 Unauthorized: wrong or deleted API key. Create a new key.
- 403 Forbidden: the key's user may not see that employee, field or time off. Use an account with a broader access level.
- 404 Not Found: wrong
companyDomainor employee/request id. - 400 Bad Request: dates not
YYYY-MM-DD, orstart/endmissing on list calls. - 503 / 429: rate limited; wait and retry with backoff.
Store the key as a VX Agents credential so it is never pasted into chat.
Usage guide
Setup
- Add a basic-auth credential: BambooHR API key as username,
xas password (profile menu > API Keys). - Pin
companyDomainto your BambooHR subdomain (acmefor https://acme.bamboohr.com); every operation needs it. - Call
listTimeOffTypesonce and note the type ids (Vacation, Sick, ...).
Who is out?
listWhosOutwithstartandend(YYYY-MM-DD; defaults to today plus 14 days). It returns employees out and company holidays, sorted by date.listTimeOffRequestswithstartandend(both required) to include pending ones; filter withstatus=requested(orapproved,denied,canceled,superceded),employeeId, ortype(comma-separated type ids). Useaction=approveto see only requests you can approve.listEmployeeDirectoryto turn employee ids into names, job titles, departments and photos. If the company has hidden the directory, usegetEmployeewithfields=firstName,lastName,jobTitle,department,supervisor,workEmailinstead (id=0is the key's own employee).
Balances
listEmployeeTimeOffPoliciesshows which policy covers each type for an employee.estimateTimeOffBalancewithendgives the projected balance per type on that date, including accruals and already-booked leave.
File or decide a request
Show the user the employee, dates, type and amount and wait for confirmation before writing.
requestTimeOfffor anemployeeIdwithstatus(requested, orapprovedif you are allowed to approve),start,end(YYYY-MM-DD),timeOffTypeId,amount(days or hours, per the type), and optionalnotes: [{"from": "employee", "note": "..."}].changeTimeOffRequestStatuswith the request id and{"status": "approved"}(ordenied,cancelled) plus an optionalnote. BambooHR notifies the employee.
Good to know
- Dates are
YYYY-MM-DD; employee ids are numeric strings. - What you can see and change follows the API key owner's access level; a manager only sees their reports.
- Responses are JSON because
Accept: application/jsonis preset. - This spec cannot change employee records, payroll or benefits, and cannot delete anything.
Source: BambooHR API reference (https://documentation.bamboohr.com/reference), checked 2026-10-21.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “BambooHR Time Off & Employee Directory” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.