Bamboo HR

Yellow.ai's integration with BambooHR allows you to connect your BambooHR account directly to your agent, enabling it to perform real-time HR operations — from fetching employee profiles and managing time-off requests to terminating employees and uploading documents — without leaving the conversation.

What can you build with this?

Common use cases include an employee self-service agent (check leave balance, apply for time-off, update emergency contacts), an HR ops agent (onboard new hires, update job info, fetch employment status), and a manager assistant agent (approve/deny time-off, view who's out, check team benefits).

Supported Actions

Action	Description
Fetch Employee Information	Fetches full employee profile using the employee ID.
Fetch Employee Time-Offs	Fetches time-off requests for an employee within a date range.
Apply Time-Offs	Submits a new time-off request on behalf of an employee.
Update Time-Offs	Approves, denies, or cancels a time-off request by request ID.
Update Employee	Updates one or more profile fields for an existing employee.
Create Employee	Creates a new employee record in BambooHR.
Upload Document	Uploads a document to an employee's file in BambooHR.
View Company Benefits	Retrieves all company-level benefit coverage types.
View Employee Benefits	Retrieves payroll deduction and benefit enrollment details for an employee.
View Employee Remaining Time-Offs	Fetches current leave balance across all time-off policies for an employee.
View Time-Off Types	Retrieves all time-off types configured in the company's BambooHR account.
View Emergency Contact Details	Fetches emergency contact records for an employee.
Add Emergency Contact Details	Adds a new emergency contact for an employee.
Update Emergency Contact Details	Updates an existing emergency contact record.
Get Job Info History	Retrieves the full job information history for an employee.
Add Job Info Row	Adds a new job info entry (e.g., promotion, transfer) for an employee.
Get Who's Out	Lists all employees on approved leave within a given date range.
Terminate Employee	Records an employee termination in BambooHR.
Fetch Employee Employment Status	Retrieves the employment status history for an employee.
Get Custom Fields Schema	Fetches all custom employee fields defined in your BambooHR account.

Integrating BambooHR with Yellow.ai

In a two-tier environment, you can connect an integration app in the Development environment. In a three-tier environment, you can connect the integration app either in Staging or Sandbox. All connected integrations are available in the live environment.

To integrate Yellow.ai with BambooHR, follow the steps below:

Switch to the Development/Staging environment and go to Extensions > Integrations > HR > Bamboo HR. Alternatively, use the Search box to quickly find the required integration.
In Give account name, enter a unique name for the integration. You can use only lowercase alphanumeric characters and underscores (_).
Enter your account's Subdomain. You can find your subdomain in the URL of your BambooHR dashboard: https://your_subdomain.bamboohr.com/home. Everything before .bamboohr.com is your subdomain.
Enter the API key. To generate it, go to your BambooHR account, click the account icon on the top right, and select API Keys. Create a new key and copy it here.
Click Connect.
To connect another account, click +Add Account and repeat the steps above. You can add a maximum of 15 accounts.

Accessing BambooHR Functions via Agent Flow

Once integrated, you can drop BambooHR action nodes anywhere in your agent flows.

Go to Automation and create or open a flow that suits your use case.
Navigate to the point in the conversation where you want to add the node. Click Add Node, then go to Integrations and select Bamboo HR.

note

When multiple accounts are connected, select the appropriate account for each node. This lets you route different actions through different BambooHR accounts within the same agent.

Action Nodes

Fetch Employee Information

Fetches the complete profile of an employee — including contact details, department, job title, supervisor, and employment status — using their BambooHR employee ID.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique numeric ID assigned to the employee in BambooHR.

Response includes: firstName, lastName, department, hireDate, workEmail, homeEmail, homePhone, mobilePhone, supervisor, location, reportsTo, employmentStatus, jobTitle, address1

📖 BambooHR API Reference — Get Employee

Fetch Employee Time-Offs

Fetches all time-off requests submitted by an employee within a specified date range. Returns the request status (approved/denied/requested), type of leave, dates, hours, and any notes from the manager or employee.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee.
Start Date	String (YYYY-MM-DD)	Start of the date range to query.
End Date	String (YYYY-MM-DD)	End of the date range to query.

Response includes: id, employeeId, name, status (with lastChanged and lastChangedByUserId), start, end, type (id + name), amount (unit + amount), dates, notes

📖 BambooHR API Reference — Get Time-Off Requests

Apply Time-Offs

Submits a new time-off request on behalf of an employee. This node first fetches the available time-off types from your BambooHR account dynamically and presents them as selectable options, so the agent always reflects your company's current leave policy.

Required parameters:

Parameter	Type	Description
Employee ID	String	The unique ID of the employee applying for leave.
Timeoff Type	String	The leave type, dynamically fetched from BambooHR (e.g., Vacation, Sick).
Start Date	String (YYYY-MM-DD)	First day of the requested leave.
End Date	String (YYYY-MM-DD)	Last day of the requested leave.
Dates	Array	Per-day breakdown — each entry needs a `ymd` (date) and `amount` (hours).
Notes	Array	Notes attached to the request — each entry needs a `from` (`employee` or `manager`) and `note` (text).

Optional parameters: amount — total leave in hours across all days.

How the time-off type is fetched

The node calls BambooHR's time-off types API in the background and maps the results to a dropdown in the agent. The timeOffTypeId sent in the actual request is resolved automatically from the selected label.

📖 BambooHR API Reference — Add a Time-Off Request

Update Time-Offs

Updates the status of an existing time-off request — approve it, deny it, or cancel it — using the request ID. A note can also be attached to explain the decision.

Required parameters:

Parameter	Type	Description
Request ID	Number	The ID of the time-off request to update. Obtained from Fetch Employee Time-Offs.
Status	String	New status: `approved`, `cancelled`, or `denied`.
Note	String	A note explaining the status change (visible to the employee if shared).

📖 BambooHR API Reference — Change a Request Status

Update Employee

Updates one or more fields on an existing employee's BambooHR profile. Only pass the fields you want to change — all others remain untouched.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee to update.

Optional parameters:

Parameter	Type	Description
First Name	String	Employee's first name.
Last Name	String	Employee's last name.
Department	String	Department name as configured in BambooHR.
Hire Date	String (YYYY-MM-DD)	Employee's official hire date.
Home Email	String	Personal email address.
Work Email	String	Work email address.
Work Phone	String	Work phone number.
Work Phone Extension	String	Extension for the work phone.
Location	String	Office location.
Address	String	Street address (address line 1).
City	String	City of residence.
State	String	State or province.
Zipcode	String	Postal/ZIP code.
Home Phone	String	Home phone number.
Mobile Phone	String	Mobile phone number.
Preferred Name	String	Preferred display name.
Reports To	String	Employee ID of the direct manager.

📖 BambooHR API Reference — Update Employee

Create Employee

Creates a brand new employee record in BambooHR. Useful for automating onboarding flows where the agent collects employee details and directly provisions the record.

Required parameters:

Parameter	Type	Description
First Name	String	Employee's first name.
Last Name	String	Employee's last name.
Work Email	String	Employee's work email — must be unique in BambooHR.

Optional parameters:

Parameter	Type	Description
Home Email	String	Personal email address.
Department	String	Department to assign the employee to.
Hire Date	String (YYYY-MM-DD)	Official start date.
Location	String	Office or work location.
Job Title	String	Employee's job title.
Work Phone	String	Work contact number.
Mobile Phone	String	Mobile number.
Reports To	String	Employee ID of the direct manager.

Sample response: { "id": "123", "firstName": "Jordan", "lastName": "Lee", "workEmail": "[email protected]", "department": "Engineering", "hireDate": "2024-01-15" }

📖 BambooHR API Reference — Add Employee

Upload Document

Uploads a file to an employee's document folder in BambooHR. Supports any standard file type. You can optionally categorize the document and choose whether the employee can view it in their self-service portal.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee.
File	String	The file content (base64 or binary depending on your flow setup).
File Name	String	The actual file name with extension (e.g., `offer_letter.pdf`).
Document Name	String	Display name shown in BambooHR (e.g., `Offer Letter - 2024`).

Optional parameters:

Parameter	Type	Description
Category	String	Document category in BambooHR (e.g., `Hiring`, `Performance`).
Share With Employee	Boolean	Set to `true` to make the document visible to the employee in their portal.

📖 BambooHR API Reference — Upload Employee File

View Company Benefits

Retrieves all benefit coverage types configured at the company level in BambooHR. No input is needed — this node returns all available coverage options, which you can display to employees or use to drive dynamic benefit selection flows in your agent.

Response includes: id, shortName, description, sortOrder

Common examples: Employee, Employee + Spouse, Employee + Family, Employee + Child, Employee + Children, Two Party, Family Only

📖 BambooHR API Reference — Get Benefit Coverages

View Employee Benefits

Retrieves the active payroll deductions and benefit enrollment details for a specific employee — including what plans they're enrolled in, how much they pay vs. the company pays, coverage type, and effective dates.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee.

Response includes: payFrequency, and a deductions array with: benefitPlanName, employeePays, companyPays, currencyCode, employeePaysType ($ or %), companyPaysType, coverageType, effectiveDate, endDate, deductionStartDate, deductionEndDate

📖 BambooHR API Reference — Get Employee Payroll Deductions

View Employee Remaining Time-Offs

Fetches the current leave balance for an employee across all time-off policies — accruing (e.g., Vacation, Sick) and discretionary (e.g., FMLA, Bereavement). Ideal for a "check my balance" flow in an employee self-service agent.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee.

Response includes: timeOffType, name, units (hours or days), balance, end (balance calculation date), policyType (accruing / discretionary), usedYearToDate

📖 BambooHR API Reference — Estimate Future Time-Off Balances

View Time-Off Types

Retrieves all time-off types configured in your BambooHR account, along with default working hours per day of the week. No input is needed. Use this before building an Apply Time-Off flow to understand what types are available.

Response includes: timeOffTypes array (with id, name, units, color, icon) and defaultHours array (hours per day of week)

📖 BambooHR API Reference — Get Time-Off Types

View Emergency Contact Details

Fetches all emergency contact records associated with an employee, including their relationship, phone numbers, address, and whether they are the primary contact.

Required parameters:

Parameter	Type	Description
Employee ID	String	The unique ID of the employee.

Response includes: id, employeeId, name, relationship, homePhone, mobilePhone, workPhone, workPhoneExtension, email, addressLine1, addressLine2, city, state, country, zipcode, primaryContact (1 = primary)

📖 BambooHR API Reference — Get Employee Table Row

Add Emergency Contact Details

Adds a new emergency contact record for an employee. Only employeeId and name are required — all other fields are optional but recommended for a complete record.

Required parameters:

Parameter	Type	Description
Employee ID	String	The unique ID of the employee.
Name	String	Full name of the emergency contact.

Optional parameters:

Parameter	Type	Description
Relationship	String	Relationship to the employee (e.g., Spouse, Parent).
Mobile Phone	String	Personal contact number.
Home Phone	String	Residential phone number.
Work Phone	String	Work phone number.
Work Phone Extension	String	Extension for the work phone.
Email	String	Email address of the contact.
Address Line 1	String	Street address.
Address Line 2	String	Apartment, suite, etc.
City	String	City.
State	String	State or province.
Country	String	Country.
Zipcode	String	Postal/ZIP code.
Primary Contact	String	`1` if this is the primary emergency contact, `0` otherwise.

📖 BambooHR API Reference — Add Employee Table Row

Update Emergency Contact Details

Updates an existing emergency contact record for an employee. You must provide both the employeeId and the rowId of the specific contact record. Only pass the fields you want to change.

Required parameters:

Parameter	Type	Description
Employee ID	String	The unique ID of the employee.
Record ID	String	The row ID of the emergency contact entry to update. Obtained from View Emergency Contact Details.

Optional parameters: Same fields as Add Emergency Contact Details. Only the fields you include will be updated.

📖 BambooHR API Reference — Update Employee Table Row

Get Job Info History

Retrieves the full job information history for an employee — every role, department, location, and reporting change recorded in BambooHR. Useful for audits, org chart generation, or display in a manager's dashboard agent.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee.

Response includes: id, employeeId, date (effective date of the entry), jobTitle, department, location, division, reportsTo

📖 BambooHR API Reference — Get Employee Table Row

Add Job Info Row

Adds a new entry to an employee's job information history. Use this to record promotions, transfers, reporting changes, or pay updates. The date field sets when the change takes effect.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee.
Effective Date	String (YYYY-MM-DD)	The date from which this job info takes effect.

Optional parameters:

Parameter	Type	Description
Job Title	String	New job title.
Department	String	New department.
Location	String	New work location.
Division	String	New division.
Reports To	String	Employee ID of the new direct manager.
Pay Rate	String	New pay rate.
Pay Type	String	Pay type (e.g., Salary, Hourly).
Pay Frequency	String	Pay frequency (e.g., Monthly, Bi-weekly).

📖 BambooHR API Reference — Add Employee Table Row

Get Who's Out

Returns a list of all employees who have approved time-off falling within the specified date range. Useful for building a "who's out today/this week" command in a manager or team lead agent.

Required parameters:

Parameter	Type	Description
Start Date	String (YYYY-MM-DD)	Start of the date range to check.
End Date	String (YYYY-MM-DD)	End of the date range to check.

Response includes: id, employeeId, name, start, end

📖 BambooHR API Reference — Get Who's Out

Terminate Employee

Records an employee termination in BambooHR by adding a new entry to their employment status history. The employmentStatus is automatically set to Terminated — you only need to provide the date and any optional context.

Required parameters:

Parameter	Type	Description
Employee ID	Number	The unique ID of the employee to terminate.
Termination Date	String (YYYY-MM-DD)	The effective date of the termination.

Optional parameters:

Parameter	Type	Description
Comment	String	Internal note or reason for termination.
Termination Type ID	String	ID for the type of termination (voluntary/involuntary). Get valid IDs from your BambooHR account metadata.
Termination Reason ID	String	ID for the reason code. Get valid IDs from your BambooHR account metadata.
Eligible For Rehire ID	String	ID indicating rehire eligibility. Get valid IDs from your BambooHR account metadata.

note

The employmentStatus field is automatically set to Terminated by the node and does not need to be passed manually. This action is irreversible through the agent — ensure the flow includes a confirmation step before executing.

📖 BambooHR API Reference — Add Employment Status Row

Fetch Employee Employment Status

Retrieves the full employment status history for an employee, including all past changes such as active, terminated, or rehired. Each entry includes the effective date, status value, and any comment attached.

Required parameters:

Parameter	Type	Description
Employee ID	String	The unique ID of the employee.

Response includes: id, employeeId, date, employmentStatus, comment

📖 BambooHR API Reference — Get Employee Table Row

Get Custom Fields Schema

Fetches the complete list of all custom employee fields defined in your BambooHR account — both standard and company-defined. Use this node to dynamically discover what fields are available before building update or fetch flows, rather than hardcoding field names.

No input parameters required.

Response includes: id, name, type (e.g., text, list, date)

📖 BambooHR API Reference — Get a List of Fields

Error Reference

All BambooHR action nodes return structured errors. The following codes may appear in the agent's error path:

Error Status	Code	HTTP Status	What it means	How to fix
`DOMAIN_OR_EMPLOYEE_NTFND`	8000	404	The subdomain or employee ID doesn't exist in BambooHR.	Verify the subdomain in your integration config and confirm the employee ID is valid.
`INVALID_ARGUMENT`	8001	400	One or more parameters are missing, wrong type, or incorrectly formatted.	Check that all required fields are present and dates follow the `YYYY-MM-DD` format.
`UNAUTHORISED`	8002	403	The API key doesn't have permission to perform this action.	Check the API key's permission scope in BambooHR under Admin > API Keys.
`INVALID_VALUE`	8003	409	A field value conflicts with existing data or fails BambooHR validation.	Verify enum values, duplicate email checks, or conflicting dates.
`AUTHENTICATION_ERROR`	9000	401	The API key is invalid or has been revoked.	Regenerate the API key in BambooHR and update it in your Yellow.ai integration config.

Supported Actions​

Integrating BambooHR with Yellow.ai​

Accessing BambooHR Functions via Agent Flow​

Action Nodes​

Fetch Employee Information​

Fetch Employee Time-Offs​

Apply Time-Offs​

Update Time-Offs​

Update Employee​

Create Employee​

Upload Document​

View Company Benefits​

View Employee Benefits​

View Employee Remaining Time-Offs​

View Time-Off Types​

View Emergency Contact Details​

Add Emergency Contact Details​

Update Emergency Contact Details​

Get Job Info History​

Add Job Info Row​

Get Who's Out​

Terminate Employee​

Fetch Employee Employment Status​

Get Custom Fields Schema​

Error Reference​

Related Resources​

Supported Actions

Integrating BambooHR with Yellow.ai

Accessing BambooHR Functions via Agent Flow

Action Nodes

Fetch Employee Information

Fetch Employee Time-Offs

Apply Time-Offs

Update Time-Offs

Update Employee

Create Employee

Upload Document

View Company Benefits

View Employee Benefits

View Employee Remaining Time-Offs

View Time-Off Types

View Emergency Contact Details

Add Emergency Contact Details

Update Emergency Contact Details

Get Job Info History

Add Job Info Row

Get Who's Out

Terminate Employee

Fetch Employee Employment Status

Get Custom Fields Schema

Error Reference

Related Resources