canonical: https://jentic.com/apis/bamboohr.com/bamboohr

# BambooHR API

The BambooHR API manages the full employee lifecycle through 164 endpoints spanning employee records, time-off requests, benefits administration, payroll data, goals tracking, applicant tracking, and training management. Supports company-scoped multi-tenant access with OAuth 2.0 or HTTP Basic authentication for programmatic HR automation.

## For AI agents

Query employee records, submit time-off requests, run custom reports, and manage benefits, payroll, and hiring pipelines across an entire BambooHR account.

## Scope

Use for employee records, time-off, benefits data, payroll records, applicant tracking, training records and HR reporting. The spec has no operation that runs a payroll or files taxes: its payroll surface is limited to reading and writing pay stubs, tax withholding records, direct deposit accounts and deduction records.

## Capabilities

- Pull employee directory listings and individual profile records with custom field support
- Submit and approve time-off requests with policy-aware balance calculations
- Generate custom reports with flexible field selection and filtering criteria
- Track applicant pipeline stages from application through hiring decision
- Administer benefits enrolment including deduction types, coverage levels, and dependents
- Process payroll data exports including pay stubs, deductions, and tax withholdings
- Register webhooks for real-time notifications on employee record changes

## Use cases

### AI Agent HR Data Retrieval

AI agents use the BambooHR API through Jentic to fetch employee records, time-off balances, and organizational data without direct BambooHR credentials. An agent searches for 'get employee details', loads the schema for the employee endpoint, and retrieves structured profile data including custom fields. This enables HR chatbots, onboarding automations, and self-service portals to pull real-time workforce data.

Example prompt: Retrieve the full employee profile for employee ID 123 including custom fields and return their department, manager, and hire date

### Time-Off Automation

Automate the full time-off lifecycle from request submission through approval and balance tracking. The API exposes endpoints to submit requests with specific date ranges and absence types, check remaining balances against policies, and update request statuses. Integrations typically connect with Slack bots or internal portals so employees request PTO without logging into BambooHR directly.

Example prompt: Submit a 2-day vacation request for employee ID 456 starting next Wednesday and verify the remaining balance afterwards

### Custom Reporting and Analytics

Generate on-demand or scheduled custom reports pulling any combination of employee fields across the workforce. The custom reports endpoint accepts field lists and filter criteria, returning structured data suitable for dashboards, compliance audits, or headcount planning. Reports can include compensation, tenure, demographics, and custom field data.

Example prompt: Generate a custom report listing all employees hired in the last 90 days with their department, title, and manager name

### Applicant Tracking Integration

Connect hiring workflows with external systems by accessing applicant data, tracking candidates through pipeline stages, and syncing hiring decisions. The applicant tracking endpoints expose job postings, applications, candidate profiles, and status transitions. Recruiting teams integrate this with scheduling tools, assessment platforms, and onboarding systems.

Example prompt: List all applicants in the 'Interview' stage for the Engineering department and return their names and application dates

### Benefits Administration Sync

Synchronize benefits enrolment data between BambooHR and insurance carriers, payroll systems, or benefits administration platforms. Endpoints cover company benefit plans, employee enrolment records, deduction types, and coverage details. Automations ensure new hires are enrolled and life-event changes propagate to downstream systems without manual data entry.

Example prompt: Retrieve all active benefit enrolments for employee ID 789 including plan names, coverage levels, and monthly deduction amounts

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | /{companyDomain}/v1/employees/directory | List the employee directory |
| GET | /{companyDomain}/v1/employees/{id}/tables/{table} | Get employee tabular data |
| POST | /{companyDomain}/v1/reports/custom | Generate a custom report |
| PUT | /{companyDomain}/v1/employees/{employeeId}/time_off/request | Submit a time-off request |
| GET | /{companyDomain}/v1/employees/{employeeId}/time_off/policies | Get time-off policies for an employee |
| GET | /{companyDomain}/v1/employees/changed | List recently changed employee records |
| GET | /{companyDomain}/v1/benefit/company_benefit | List company benefit plans |
| GET | /{companyDomain}/v1/employees/{employeeId}/time_off/calculator | Calculate time-off balance |

## Key resources

- **Employees** — Employee profiles, directory listings, custom fields, photos, and change tracking
- **Time Off** — Time-off requests, policy balances, status updates, and calculators
- **Benefits** — Company benefit plans, employee enrolments, deduction types, and coverage
- **Payroll** — Payroll data, pay stubs, tax withholdings, and deduction records
- **Reports** — Custom and pre-built reports with flexible field selection
- **Applicant Tracking** — Job postings, applications, candidate profiles, and hiring pipeline stages
- **Webhooks** — Event-driven notifications for employee record changes

## Why Jentic

- **Setup:** Hand-wiring BambooHR means picking between its OAuth 2.0 authorization code flow and HTTP Basic secret key, building the company-scoped URL for every call, and handling 503 with a back-off because BambooHR publishes no fixed rate budget. Through Jentic it is one install, an import of BambooHR, and the credential stored once.
- **Permission scoping:** Scope the agent to the operations, and the specific employee record, it needs: BambooHR puts the employee id in the URL path (/{companyDomain}/v1/employees/{employeeId}/...), so a rule can pin your agent to one employee. You choose which operations it may call, so reading time-off balances need not come with the pay stub and withholding endpoints.
- **Credential handling:** Your BambooHR secret key or OAuth token is stored encrypted by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search by intent (e.g., 'get employee time off balance') and Jentic returns matching BambooHR operations with their input schemas and required path parameters, so the agent can call the right endpoint without parsing BambooHR's documentation.

## Related APIs

- **HiBob API** — Modern HRIS platform with employee management, time-off, and lifecycle workflows
- **Personio API** — European HR platform covering employee records, absence, attendance, and payroll
- **Gusto Embedded Payroll API** — Payroll processing, tax filing, and contractor payments for US companies
- **Lever API** — Dedicated ATS with candidate pipeline, interview scheduling, and offer management

## FAQ

### Which OpenAPI spec does Jentic use for the BambooHR API?

Jentic uses a curated, agent-optimized spec rather than BambooHR's own published document. BambooHR does publish an OpenAPI specification, offered as a download on its Postman Collection documentation page at `https://openapi.bamboohr.io/main/latest/docs/openapi/public-openapi.yaml`. The curated spec here is not that file: an operation-by-operation comparison found 45 operations in the curated spec that the published one does not contain, including the pay stub, tax withholding, direct deposit and time-tracking clock-entry endpoints. Those operations stay callable because the curated spec is kept.

### What authentication does the BambooHR API use?

The API supports two authentication methods: OAuth 2.0 authorization code flow (recommended for production integrations) and HTTP Basic authentication using your API secret key as the username with any random string as the password. The OAuth flow authorizes at `https://{companyDomain}.bamboohr.com/authorize.php` and exchanges tokens at `https://{companyDomain}.bamboohr.com/token.php`. Every operation in the spec accepts either scheme.

### Can I generate custom employee reports with the BambooHR API?

Yes. POST to /{companyDomain}/v1/reports/custom with a JSON body specifying the fields you want (e.g., firstName, lastName, department, hireDate) and optional filter criteria. The response returns structured tabular data. BambooHR marks this endpoint deprecated in its reference documentation, with the note 'Deprecated. Use Datasets > Get Data from Dataset instead.', so treat it as legacy for new work. You can also retrieve pre-built reports via GET /{companyDomain}/v1/reports/{id} using the report ID from the BambooHR UI.

### What are the rate limits for the BambooHR API?

BambooHR publishes no numeric rate limit. Its API details documentation states 'Implementations should always be ready for a 503 Service Unavailable response' and adds that commonly this is due to rate limiting, with a Retry-After header that may be available. So handle 503 and back off rather than coding to a fixed budget. For bulk work, call GET /{companyDomain}/v1/employees/changed to fetch only modified records instead of re-reading the directory.

### How do I submit a time-off request through Jentic?

Search for 'submit employee time off request', load the schema for PUT /{companyDomain}/v1/employees/{employeeId}/time_off/request, and execute with the employee ID, date range, and time-off type. Before submitting, call GET /{companyDomain}/v1/employees/{employeeId}/time_off/calculator to check the available balance. Both operations run through your own Jentic One instance, which injects the BambooHR credential at call time.

### Does the BambooHR API support webhooks for real-time updates?

Yes. The Webhooks resource allows you to register HTTP callback URLs that receive notifications when employee records change. BambooHR's event-based webhooks document three event types: employee.created when an employee record was created, employee.updated when one or more monitored fields on an employee record were changed, and employee.deleted when an employee record was deleted. The updated event fires only for the fields you select as monitor fields, which GET /{companyDomain}/v1/webhooks/monitor_fields lists. This eliminates the need for polling the employees/changed endpoint for near-real-time integrations.

### Is there a BambooHR MCP server?

You do not need an MCP server to give your agent BambooHR. Jentic connects it directly from the API Directory: import BambooHR, store your API secret key or OAuth client once, and your agent calls the 164 endpoints on demand. Nothing extra is loaded into the agent's context, because operations are discovered when they are needed rather than declared up front.

### Can I limit what my agent is allowed to do with BambooHR?

Yes, and BambooHR's URL shape makes it specific. Employee operations carry the employee id in the path (/{companyDomain}/v1/employees/{employeeId}/time_off/policies, /{companyDomain}/v1/employees/{id}/tables/{table}), so a rule can pin the agent to one employee record as well as to the operations it needs. A read-only onboarding assistant can be scoped to GET /{companyDomain}/v1/employees/directory and the time-off calculator, with the PUT that submits a request and the payroll pay stub and withholding endpoints left out entirely.