Execute BambooHR secondary workflows: time off requests, PTO balances,
benefits administration, and employee files/photos.
Use when managing time off, checking PTO balances, handling benefits data,
or working with employee documents in BambooHR.
Trigger with phrases like "bamboohr time off", "bamboohr PTO", "bamboohr benefits",
"bamboohr vacation", "bamboohr files", "bamboohr leave request".
Execute BambooHR secondary workflows: time off requests, PTO balances,
benefits administration, and employee files/photos.
Use when managing time off, checking PTO balances, handling benefits data,
or working with employee documents in BambooHR.
Trigger with phrases like "bamboohr time off", "bamboohr PTO", "bamboohr benefits",
"bamboohr vacation", "bamboohr files", "bamboohr leave request".
allowed-tools
Read, Write, Edit, Bash(curl:*), Grep
version
1.0.0
license
MIT
author
Jeremy Longshore <jeremy@intentsolutions.io>
tags
["saas","hr","bamboohr","timeoff","benefits"]
compatible-with
claude-code
BambooHR Core Workflow B — Time Off, Benefits & Files
Overview
Secondary BambooHR workflows covering time off requests, PTO balance tracking, employee file management, photos, goals, and training records.
Prerequisites
Completed bamboohr-install-auth setup
BambooHRClient from bamboohr-sdk-patterns
API key with time-off and files permissions
Instructions
Step 1: List Time Off Requests
// GET /time_off/requests/?start=YYYY-MM-DD&end=YYYY-MM-DDconst requests = await client.request<any[]>(
'GET',
`/time_off/requests/?start=2026-03-01&end=2026-03-31&status=approved`,
);
for (const req of requests) {
console.log(`${req.employeeId}: ${req.start} to ${req.end} (${req.type.name})`);
console.log(` Status: ${req.status.status} | ${req.amount.amount}${req.amount.unit}`);
}
// GET /employees/{id}/time_off/calculator?end=YYYY-MM-DDconst balances = await client.request<any>(
'GET',
`/employees/123/time_off/calculator?end=2026-12-31`,
);
// Returns balances for each time off typefor (const [typeId, balance] ofObject.entries(balances)) {
const b = balance asany;
console.log(`${b.name}: ${b.balance} days remaining (accruing ${b.accrualRate}/period)`);
}
Step 5: Get Time Off Policies and Types
// GET /meta/time_off/types — list all time off typesconst types = await client.request<Record<string, any>>(
'GET', '/meta/time_off/types',
);
for (const [id, type] ofObject.entries(types)) {
console.log(`Type ${id}: ${(typeasany).name}`);
}
// GET /time_off/policies — list all time off policiesconst policies = await client.request<any[]>('GET', '/meta/time_off/policies');
for (const policy of policies) {
console.log(`Policy: ${policy.name} (${policy.type})`);
}
Step 6: Employee Files
// GET /employees/{id}/files/view — list all files for an employeeconst files = await client.request<{ categories: any[] }>(
'GET', `/employees/123/files/view`,
);
for (const category of files.categories) {
console.log(`Category: ${category.name}`);
for (const file of category.files || []) {
console.log(` ${file.name} (${file.originalFileName}) — ${file.createdDate}`);
}
}
// GET /employees/{id}/files/{fileId}/ — download a specific file// Returns binary file contentconst fileRes = awaitfetch(`${BASE}/employees/123/files/42/`, {
headers: { Authorization: AUTH },
});
const fileBuffer = await fileRes.arrayBuffer();
// POST /employees/{id}/files — upload a new fileconst formData = newFormData();
formData.append('file', newBlob([fileContent]), 'offer-letter.pdf');
formData.append('fileName', 'Offer Letter 2026');
formData.append('category', 'Unsigned Documents');
awaitfetch(`${BASE}/employees/123/files`, {
method: 'POST',
headers: { Authorization: AUTH },
body: formData,
});
// GET /v1/performance/employees/{id}/goals — list goals for an employeeconst goals = await client.request<{ goals: any[] }>(
'GET', `/v1/performance/employees/123/goals`,
);
for (const goal of goals.goals) {
console.log(`${goal.title} — ${goal.percentComplete}% (${goal.status})`);
}
// GET /training/record/{employeeId} — get training recordsconst training = await client.request<any[]>(
'GET', `/training/record/123`,
);
for (const record of training) {
console.log(`${record.type}: completed ${record.completedDate}`);
}
Output
Time off requests listed, created, and approved/denied
PTO balances and accrual rates retrieved
Employee files listed, downloaded, and uploaded
Photos fetched and updated
Goals and training records accessed
Error Handling
Error
Cause
Solution
400 on time off create
Missing required date fields
Include start, end, dates object
403 on file download
Key lacks file access
Use API key with file permissions
404 on time off type
Invalid timeOffTypeId
Fetch valid types from /meta/time_off/types
409 on overlapping request
Existing request for same dates
Check existing requests first
Enterprise Considerations
Audit compliance: Time off changes are logged — check audit trail for SOX/HIPAA
Bulk time off: Use the custom report endpoint with time-off fields for bulk exports
Holiday calendars: BambooHR manages company holidays separately from PTO; query via the Who's Out calendar
File retention: BambooHR stores files indefinitely; implement your own retention policies for downloads
