Bamboohr

Learn how to use Bamboohr with Composio

Overview

SLUG: BAMBOOHR

Description

BambooHR is an American technology company that provides human resources software as a service.

Authentication Details

client_id
stringRequired
client_secret
stringRequired
oauth_redirect_uri
stringDefaults to https://backend.composio.dev/api/v1/auth-apps/add
scopes
stringDefaults to application,application.write,job_opening,job_opening.write,benefit,benefit.write,email,openid,company:administration,company:administration.write,company:info,company_file,company_file.write,data_cleaner,error_management,employee,employee.write,employee:assets,employee:assets.write,employee:compensation,employee:compensation.write,employee:contact,employee:contact.write,employee:custom_fields,employee:custom_fields.write,employee:custom_fields_encrypted,employee:custom_fields_encrypted.write,employee:demographic,employee:demographic.write,employee:dependent,employee:dependent.write,employee:dependent:ssn,employee:dependent:ssn.write,employee:education,employee:education.write,employee:emergency_contacts,employee:emergency_contacts.write,employee:file,employee:file.write,employee:identification,employee:identification.write,employee:job,employee:job.write,employee:management,employee:management.write,employee:name,employee:name.write,employee:payroll,employee:payroll.write,employee:photo,employee:photo.write,employee:providers,employee:providers.write,employee:providers:payroll,employee:providers:payroll.write,employee:vaccination,employee:vaccination.write,goal,goal.write,sensitive_employee:address,sensitive_employee:address.write,sensitive_employee:creditcards,sensitive_employee:creditcards.write,sensitive_employee:protected_info,sensitive_employee:protected_info.write,tasks,tasks.write,access_level,benchmarking:compensation,field,field.write,gridlets,offline_access,public.user,training,training.write,user,user:management,user:management.write,webhooks,webhooks.write,payroll,payroll.write,report,time_off,time_off.write,time_tracking,time_tracking.write
subdomain
stringRequired
basic_encoded
stringRequired

Connecting to Bamboohr

Create an auth config

Use the dashboard to create an auth config for the Bamboohr toolkit. This allows you to connect multiple Bamboohr accounts to Composio for agents to use.

1

Select App

Navigate to Bamboohr.

2

Configure Auth Config Settings

Select among the supported auth schemes of and configure them here.

3

Create and Get auth config ID

Click “Create Bamboohr Auth Config”. After creation, copy the displayed ID starting with ac_. This is your auth config ID. This is not a sensitive ID — you can save it in environment variables or a database. This ID will be used to create connections to the toolkit for a given user.

Connect Your Account

Using OAuth2

1from composio import Composio
2
3# Replace these with your actual values
4bamboohr_auth_config_id = "ac_YOUR_BAMBOOHR_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/application
6
7composio = Composio()
8
9
10def authenticate_toolkit(user_id: str, auth_config_id: str):
11 connection_request = composio.connected_accounts.initiate(
12 user_id=user_id,
13 auth_config_id=auth_config_id,
14 )
15
16 print(
17 f"Visit this URL to authenticate Bamboohr: {connection_request.redirect_url}"
18 )
19
20 # This will wait for the auth flow to be completed
21 connection_request.wait_for_connection(timeout=15)
22 return connection_request.id
23
24
25connection_id = authenticate_toolkit(user_id, bamboohr_auth_config_id)
26
27# You can also verify the connection status using:
28connected_account = composio.connected_accounts.get(connection_id)
29print(f"Connected account: {connected_account}")

Using API Key

1from composio import Composio
2
3# Replace these with your actual values
4bamboohr_auth_config_id = "ac_YOUR_BAMBOOHR_CONFIG_ID" # Auth config ID created above
5user_id = "0000-0000-0000" # UUID from database/app
6
7composio = Composio()
8
9def authenticate_toolkit(user_id: str, auth_config_id: str):
10 # Replace this with a method to retrieve an API key from the user.
11 # Or supply your own.
12 user_api_key = input("[!] Enter API key")
13
14 connection_request = composio.connected_accounts.initiate(
15 user_id=user_id,
16 auth_config_id=auth_config_id,
17 config={"auth_scheme": "API_KEY", "val": {"generic_api_key": user_api_key}}
18 )
19
20 # API Key authentication is immediate - no redirect needed
21 print(f"Successfully connected Bamboohr for user {user_id}")
22 print(f"Connection status: {connection_request.status}")
23
24 return connection_request.id
25
26
27connection_id = authenticate_toolkit(user_id, bamboohr_auth_config_id)
28
29# You can verify the connection using:
30connected_account = composio.connected_accounts.get(connection_id)
31print(f"Connected account: {connected_account}")

Tools

Executing tools

To prototype you can execute some tools to see the responses and working on the Bamboohr toolkit’s playground

Python
1from composio import Composio
2from openai import OpenAI
3import json
4
5openai = OpenAI()
6composio = Composio()
7
8# User ID must be a valid UUID format
9user_id = "0000-0000-0000" # Replace with actual user UUID from your database
10
11tools = composio.tools.get(user_id=user_id, toolkits=["BAMBOOHR"])
12
13print("[!] Tools:")
14print(json.dumps(tools))
15
16def invoke_llm(task = "What can you do?"):
17 completion = openai.chat.completions.create(
18 model="gpt-4o",
19 messages=[
20 {
21 "role": "user",
22 "content": task, # Your task here!
23 },
24 ],
25 tools=tools,
26 )
27
28 # Handle Result from tool call
29 result = composio.provider.handle_tool_calls(user_id=user_id, response=completion)
30 print(f"[!] Completion: {completion}")
31 print(f"[!] Tool call result: {result}")
32
33invoke_llm()

Tool List

Tool Name: Create Candidate Application

Description

Tool to create a candidate application. Use when adding a new applicant to a specific job opening in BambooHR ATS.

Action Parameters

address
string
city
string
collegeName
string
country
string
coverLetter
object
dateAvailable
string
desiredSalary
string
email
string
firstName
stringRequired
highestEducation
string
jobId
integerRequired
lastName
stringRequired
linkedinUrl
string
phoneNumber
string
references
string
referredBy
string
resume
object
source
string
state
string
websiteUrl
string
zip
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Job Opening

Description

Tool to create a new job opening in BambooHR ATS. Use when you need to open a new job for applicants.

Action Parameters

applicationQuestionAddress
string
applicationQuestionCollege
string
applicationQuestionCoverLetter
string
applicationQuestionDateAvailable
string
applicationQuestionDesiredSalary
string
applicationQuestionHighestEducation
string
applicationQuestionLinkedinUrl
string
applicationQuestionReferences
string
applicationQuestionReferredBy
string
applicationQuestionResume
string
applicationQuestionWebsiteUrl
string
compensation
string
department
string
employmentType
string
hiringLead
integerRequired
internalJobCode
string
jobDescription
string
jobLocation
integer
jobStatus
stringRequired
minimumExperience
string
postingTitle
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Job Applications

Description

Tool to list job applications with optional filters. Use when retrieving ATS applications for reporting or integration.

Action Parameters

endDate
string
jobIds
array
limit
integer
offset
integer
source
string
startDate
string
status
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Benefit Coverages

Description

Tool to retrieve standard benefit coverage options. Use when you need to fetch all or specific coverages before configuring benefit plans.

Action Parameters

coverage_id
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Member Benefit Events

Description

Tool to list member benefit events. Use when you need to fetch all benefit events visible to the authenticated user.

Action Parameters

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Company EINs

Description

Tool to retrieve company Employer Identification Numbers (EINs). Use when you need to fetch your account's EINs after authenticating.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Company Information

Description

Tool to retrieve company information. Use when you need details about the current account's settings.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create File Category

Description

Tool to create new company file categories. Use when organizing company files by adding new categories after confirming desired names.

Action Parameters

categories
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Time Off Request

Description

Tool to submit a new time off request. Use after confirming employee ID and valid payload.

Action Parameters

amount
number
dates
array
employeeId
stringRequired
end
stringRequired
notes
array
previousRequest
integer
start
stringRequired
status
stringRequired
timeOffTypeId
integerRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Datasets

Description

Tool to list available datasets via the Datasets API. Use when you need to discover available dataset schemas before querying data.

Action Parameters

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Delete Time-Off Request

Description

Tool to delete (withdraw) a time-off request. Use when you need to cancel a pending time-off request.

Action Parameters

requestId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Employee Dependent

Description

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.

Action Parameters

addressLine1
string
addressLine2
string
city
string
country
string
dateOfBirth
stringRequired
employeeId
integerRequired
firstName
stringRequired
gender
string
homePhone
string
isStudent
string
isUsCitizen
string
lastName
stringRequired
middleName
string
relationship
string
ssn
string
state
string
zipCode
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get All Employee Dependents

Description

Tool to retrieve all employee dependents. Use after ensuring your API key has access to benefit settings.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Employee

Description

Tool to create a new employee record. Use when adding employees via BambooHR API. Returns the new employee's ID.

Action Parameters

firstName
stringRequired
lastName
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Create Employee File Category

Description

Tool to create new employee file categories. Use when organizing employee files by adding new categories after confirming desired names.

Action Parameters

categories
arrayRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Changed Employees

Description

Tool to get employees inserted, updated, or deleted since a given timestamp. Use when fetching incremental HR changes.

Action Parameters

since
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Company Files

Description

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.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Upload Company File

Description

Tool to upload a new company file. Use when you need to add a file to BambooHR after confirming its category and share settings.

Action Parameters

category
stringRequired
file
object
fileName
stringRequired
rawContent
string
rawMimetype
string
share
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get All Employees

Description

Retrieves all employees from BambooHR including their basic information and status.

Action Parameters

Action Response

data
arrayRequired
error
string
links
objectRequired
meta
objectRequired
successful
booleanRequired

Tool Name: Get Applicant Statuses

Description

Tool to retrieve applicant statuses. Use when you need to list ATS statuses for your company; requires ATS settings access.

Action Parameters

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Custom Employee Fields

Description

Tool to fetch custom employee field values. Use when you need to retrieve only custom fields for all employees.

Action Parameters

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Run Custom Report

Description

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.

Action Parameters

fields
array
filters[lastChanged][includeNull]
string
filters[lastChanged][value]
string
format
stringDefaults to JSON
onlyCurrent
boolean
reportId
string
title
string

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Employee

Description

Tool to retrieve detailed information for a specific employee. Use when you need individual employee data by ID.

Action Parameters

employeeId
stringRequired
fields
array

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Employee Photo

Description

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.

Action Parameters

employee_id
stringRequired
size
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Hiring Leads

Description

Tool to retrieve potential hiring leads for creating a new job opening. Use when gathering candidate recommendations before posting a job.

Action Parameters

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Job Summaries

Description

Tool to retrieve a list of ATS job summaries. Use when you need an overview of all job postings and their key details.

Action Parameters

sortBy
string
sortOrder
string
statusGroups
string

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Departments Metadata

Description

Tool to list department metadata. Use after needing all available department codes and names.

Action Parameters

limit
integer
name_contains
string
offset
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Meta Divisions

Description

Tool to list all division metadata. Use after authenticating to fetch the account's divisions.

Action Parameters

limit
integer
name_contains
string
offset
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: List Employment Status Metadata

Description

Tool to list all employment status metadata. Use when you need all defined employment statuses for the company.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Meta Job Titles

Description

Tool to retrieve job title metadata. Uses the list-field metadata endpoint and extracts the options for the `jobTitle` field.

Action Parameters

include_archived
boolean
limit
integer
name_contains
string
offset
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Meta Locations

Description

Tool to list location metadata. Use when you need all configured company locations for lookups.

Action Parameters

include_archived
boolean
limit
integer
name_contains
string
offset
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Time-Off Types Metadata

Description

Tool to list time-off type metadata. Use when you need to discover available time-off types before creating time-off requests.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Report

Description

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.

Action Parameters

fd
stringDefaults to yes
format
stringDefaults to JSON
report_id
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Time-Off Balances

Description

Tool to retrieve time-off balances for employees. Use when you need current balances across your team.

Action Parameters

employee_ids
array
end_date
string

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: Get Time-Off Request

Description

Tool to retrieve details of a specific time-off request. Use when you need to view a particular time-off request by its ID after listing requests.

Action Parameters

requestId
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Time-Off Requests

Description

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.

Action Parameters

action
stringDefaults to view
employeeId
string
end
stringRequired
id
string
start
stringRequired
status
string
type
string

Action Response

data
arrayRequired
error
string
successful
booleanRequired

Tool Name: List Company Reports

Description

Tool to list all available company and custom reports. Use after confirming account setup.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Country Options

Description

Tool to retrieve all available country options. Use when you need a complete list of selectable countries before updating or validating country fields.

Action Parameters

limit
integer
name_contains
string
offset
integer

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get List Field Details

Description

Tool to get details for all list fields. Use when you need to discover list field options before using them.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Tabular Fields Metadata

Description

Tool to list tabular table fields metadata. Use when you need standard table structures before accessing table rows.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Get Users

Description

Tool to list active users with basic info. Use when you need to retrieve current users' IDs, names, and emails.

Action Parameters

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Employee

Description

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 department to Sales".

Action Parameters

employee_id
stringRequired
fields
objectRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired

Tool Name: Update Time Off Request

Description

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".

Action Parameters

request_id
stringRequired
status
stringRequired

Action Response

data
objectRequired
error
string
successful
booleanRequired