# BambooHR — how to use (mcp.ai)

Connect your BambooHR account and use 42 tools for human resources straight from your AI agent. Connect with your own API key. BambooHR is a cloud-based human resources management system (HRMS) that helps businesses manage their employees, payroll, and benefits.

## Option A — via MCP (recommended)
Remote MCP endpoint (HTTP, streamable): `https://api.mcp.ai/p_bamboohr?ms=1787296020000`
Add it as a custom/remote MCP connector in your client (Claude, Cursor, VS Code…), then authenticate when prompted. Once connected, ask the agent to use the server's tools (e.g. `bamboohr_ats_create_candidate`).

## Option B — via direct REST API
Base URL: `https://api.mcp.ai/api/bamboohr`
Auth: `Authorization: Bearer sk_live_…` — create a workspace API key at https://mcp.ai/settings/api-keys
Discover endpoints: `GET https://api.mcp.ai/api/bamboohr/_endpoints`

### Endpoints
- `POST https://api.mcp.ai/api/bamboohr/ats/create/candidate` — Tool to create a candidate application. Use when adding a new applicant to a specific job opening in BambooHR ATS.
  - body: { zip?: string, city?: string, email?: string, jobId: integer, state?: string, resume?: object, source?: string, address?: string, country?: string, lastName: string, firstName: string, references?: string, referredBy?: string, websiteUrl?: string, collegeName?: string, coverLetter?: object, linkedinUrl?: string, phoneNumber?: string, dateAvailable?: string, desiredSalary?: string, highestEducation?: string }
- `POST https://api.mcp.ai/api/bamboohr/ats/create/job/opening` — Tool to create a new job opening in BambooHR ATS. Use when you need to open a new job for applicants.
  - body: { jobStatus: string, department?: string, hiringLead: integer, jobLocation?: integer, compensation?: string, postingTitle: string, employmentType: string, jobDescription: string, internalJobCode?: string, minimumExperience?: string, applicationQuestionResume?: string, applicationQuestionAddress?: string, applicationQuestionCollege?: string, applicationQuestionReferences?: string, applicationQuestionReferredBy?: string, applicationQuestionWebsiteUrl?: string, applicationQuestionCoverLetter?: string, applicationQuestionLinkedinUrl?: string, applicationQuestionDateAvailable?: string, applicationQuestionDesiredSalary?: string, applicationQuestionHighestEducation?: string }
- `POST https://api.mcp.ai/api/bamboohr/ats/get/applications` — Tool to list job applications with optional filters. Use when retrieving ATS applications for reporting or integration.
  - body: { page?: integer, jobId?: integer, jobStatusGroups?: string, applicationStatus?: string, applicationStatusId?: integer }
- `POST https://api.mcp.ai/api/bamboohr/benefit/get/coverages` — Tool to retrieve standard benefit coverage options. Use when you need to fetch all or specific coverages before configuring benefit plans.
  - body: { coverage_id?: string }
- `POST https://api.mcp.ai/api/bamboohr/benefit/get/member/events` — Tool to list member benefit events. Use when you need to fetch all benefit events visible to the authenticated user.
  - body: { limit?: integer, offset?: integer }
- `POST https://api.mcp.ai/api/bamboohr/company/get/eins` — Tool to retrieve company Employer Identification Numbers (EINs). Use when you need to fetch your account's EINs after authenticating.
- `POST https://api.mcp.ai/api/bamboohr/company/get/information` — Tool to retrieve company information. Use when you need details about the current account's settings.
- `POST https://api.mcp.ai/api/bamboohr/create/file/category` — Tool to create new company file categories. Use when organizing company files by adding new categories after confirming desired names.
  - body: { categories: string[] }
- `POST https://api.mcp.ai/api/bamboohr/create/time/off/request` — Tool to submit a new time off request. Use after confirming employee ID and valid payload.
  - body: { end: string, dates?: object[], notes?: object[], start: string, amount?: number, status: string, employeeId: string, timeOffTypeId: integer, previousRequest?: integer }
- `POST https://api.mcp.ai/api/bamboohr/datasets/list` — Tool to list available datasets via the Datasets API. Use when you need to discover available dataset schemas before querying data.
- `POST https://api.mcp.ai/api/bamboohr/dependents/create` — Tool to add a dependent to an employee. Use when a new dependent needs to be recorded for benefits or HR tracking. Ensure the employee record exists before calling this tool.
  - body: { ssn?: string, city?: string, state?: string, gender?: string, country?: string, zipCode?: string, lastName: string, firstName: string, homePhone?: string, isStudent?: string, employeeId: integer, middleName?: string, dateOfBirth: string, isUsCitizen?: string, addressLine1?: string, addressLine2?: string, relationship?: string }
- `POST https://api.mcp.ai/api/bamboohr/dependents/get/all` — Tool to retrieve all employee dependents. Use after ensuring your API key has access to benefit settings.
- `POST https://api.mcp.ai/api/bamboohr/employee/create` — Tool to create a new employee record. Use when adding employees via BambooHR API. Returns the new employee's ID.
  - body: { lastName: string, firstName: string }
- `POST https://api.mcp.ai/api/bamboohr/employee/files/create/category` — Tool to create new employee file categories. Use when organizing employee files by adding new categories after confirming desired names.
  - body: { categories: string[] }
- `POST https://api.mcp.ai/api/bamboohr/employee/get/changed` — Tool to get employees inserted, updated, or deleted since a given timestamp. Use when fetching incremental HR changes.
  - body: { since: string }
- `POST https://api.mcp.ai/api/bamboohr/files/list` — Tool to list company file categories and their files. Use when you need to retrieve all company files organized by category after confirming file inventory exists.
- `POST https://api.mcp.ai/api/bamboohr/files/upload` — Tool to upload a new company file. Use when you need to add a file to BambooHR after confirming its category and share settings.
  - body: { file?: object, share: string, category: string, fileName: string, rawContent?: string, rawMimetype?: string }
- `POST https://api.mcp.ai/api/bamboohr/get/all/employees` — Retrieves all employees from the BambooHR employee directory including their basic information and status.
- `POST https://api.mcp.ai/api/bamboohr/get/applicant/statuses` — Tool to retrieve applicant statuses. Use when you need to list ATS statuses for your company; requires ATS settings access.
- `POST https://api.mcp.ai/api/bamboohr/get/custom/employee/fields` — Tool to fetch custom employee field values. Use when you need to retrieve only custom fields for all employees.
- `POST https://api.mcp.ai/api/bamboohr/get/custom/reports` — Tool to run a custom report by ID or ad-hoc fields. Use when you need to execute a saved report or generate an ad-hoc report and retrieve its results in JSON or file format.
  - body: { title?: string, fields?: string[], format?: string, reportId?: string, onlyCurrent?: boolean, filters_last_changed_value?: string, filters_last_changed_include_null?: string }
- `POST https://api.mcp.ai/api/bamboohr/get/employee` — Tool to retrieve detailed information for a specific employee. Use when you need individual employee data by ID.
  - body: { fields?: string[], employeeId: string }
- `POST https://api.mcp.ai/api/bamboohr/get/employee/photo` — Tool to retrieve an employee's profile photo by size. Use when you need to download the image binary for the specified employee after confirming their ID.
  - body: { size: string, employee_id: string }
- `POST https://api.mcp.ai/api/bamboohr/get/hiring/leads` — Tool to retrieve potential hiring leads (employees who can manage job openings) for use in creating a new job opening. The API key owner must have access to ATS settings.
- `POST https://api.mcp.ai/api/bamboohr/get/job/summaries` — Tool to retrieve a list of ATS job summaries. Use when you need an overview of all job postings and their key details.
  - body: { sortBy?: string, sortOrder?: string, statusGroups?: string }
- `POST https://api.mcp.ai/api/bamboohr/get/meta/departments` — Tool to list department metadata. Use after needing all available department codes and names.
  - body: { limit?: integer, offset?: integer, name_contains?: string }
- `POST https://api.mcp.ai/api/bamboohr/get/meta/divisions` — Tool to list all division metadata. Use after authenticating to fetch the account's divisions.
  - body: { limit?: integer, offset?: integer, name_contains?: string }
- `POST https://api.mcp.ai/api/bamboohr/get/meta/employment/statuses` — Tool to list all employment status metadata. Use when you need all defined employment statuses for the company.
- `POST https://api.mcp.ai/api/bamboohr/get/meta/job/titles` — Tool to retrieve job title metadata. Uses the list-field metadata endpoint and extracts the options for the `jobTitle` field.
  - body: { limit?: integer, offset?: integer, name_contains?: string, include_archived?: boolean }
- `POST https://api.mcp.ai/api/bamboohr/get/meta/locations` — Tool to list location metadata. Use when you need all configured company locations for lookups.
  - body: { limit?: integer, offset?: integer, name_contains?: string, include_archived?: boolean }
- `POST https://api.mcp.ai/api/bamboohr/get/meta/time/off/types` — Tool to list time-off type metadata. Use when you need to discover available time-off types before creating time-off requests.
- `POST https://api.mcp.ai/api/bamboohr/get/report` — Tool to fetch a built-in or published report in JSON or other formats. Use when you need to retrieve report data or download report files after specifying the report ID and desired output format.
  - body: { fd?: string, format?: string, report_id: string }
- `POST https://api.mcp.ai/api/bamboohr/get/time/off/balances` — Tool to retrieve time-off balances for employees. Use when you need current balances across your team.
  - body: { end_date?: string, employee_ids?: integer[], max_employees?: integer }
- `POST https://api.mcp.ai/api/bamboohr/get/time/off/policies` — Tool to list time-off policies with accrual rates and details. This action retrieves policy configuration including accrual amounts, schedules, maximum accrual limits, and rollover settings. Use this 
- `POST https://api.mcp.ai/api/bamboohr/get/time/off/requests` — Tool to list time-off requests within a date range. Use after confirming start and end dates; supports optional filters for status, employee, and time off type.
  - body: { id?: string, end: string, type?: string, start: string, action?: string, status?: string, employeeId?: string }
- `POST https://api.mcp.ai/api/bamboohr/list/builtin/reports` — Tool to list all available company and custom reports. Use after confirming account setup. Requires 'report' scope for OAuth or an API key with report access permissions.
- `POST https://api.mcp.ai/api/bamboohr/meta/get/countries` — Tool to retrieve all available country options. Use when you need a complete list of selectable countries before updating or validating country fields.
  - body: { limit?: integer, offset?: integer, name_contains?: string }
- `POST https://api.mcp.ai/api/bamboohr/meta/get/list/field/details` — Tool to get details for all list fields. Use when you need to discover list field options before using them.
- `POST https://api.mcp.ai/api/bamboohr/meta/get/tabular/fields` — Tool to list tabular table fields metadata. Use when you need standard table structures before accessing table rows.
- `POST https://api.mcp.ai/api/bamboohr/meta/get/users` — Tool to list active users with basic info. Use when you need to retrieve current users' IDs, names, and emails.
- `POST https://api.mcp.ai/api/bamboohr/update/employee` — Tool to update fields on a specified employee record. Use when you need to modify employee properties via BambooHR API after confirming the target employee ID. Example: "Update employee 12345's depart
  - body: { fields: object, employee_id: string }
- `POST https://api.mcp.ai/api/bamboohr/update/time/off/request` — Tool to update the status of an existing time-off request. Use when you need to approve, deny, or cancel a request after reviewing it. Example: "Approve time-off request 12345".
  - body: { note?: string, status: string, request_id: string }

## Example prompts
- "What can I do in BambooHR?"
- "Show me a summary of my BambooHR account"

## More
- Page: https://mcp.ai/bamboohr
- Agent spec (llms.txt): https://mcp.ai/bamboohr/llms.txt
- Postman collection: https://mcp.ai/bamboohr/postman.json