Skip to main content

BambooHR

BambooHR is a human resources information system (HRIS) that helps organizations manage employee data, time off, benefits, performance, training, and HR workflows. It's designed for small to medium-sized businesses and provides a centralized platform for all HR operations.

Authentication​

BambooHR uses API Key authentication.

General Settings​

Before using the connector, you need to configure:

  • Company Domain - Your BambooHR subdomain (the text before .bamboohr.com in your company's BambooHR URL). For example, if you access BambooHR at https://mycompany.bamboohr.com, your company domain is mycompany.

Setting up API Key​

Each user can generate their own API key for authentication.

  1. Log in to your BambooHR account

  2. Click your name in the lower left-hand corner of any page

  3. Select API Keys from the menu

  4. Click Create a new key (or similar button)

  5. Give your key a descriptive name (e.g., "Webrix Integration")

  6. Click Generate Key

  7. IMPORTANT: Copy the API key immediately - it will only be shown once

  8. In Webrix:

    • Paste the API key value
    • Enter your Company Domain under General Settings (e.g., mycompany)
    • Click Save Changes
caution

API Keys have the same permissions as the user who generated them. Store them securely and never commit them to source control. If a key is compromised, delete it in BambooHR and generate a new one.

Available Operations​

The BambooHR connector provides 27 tools across 7 categories:

Employee Management (7 tools)​

  • List Employees Directory - Get employee directory with basic info
  • Get Employee - Retrieve detailed employee data with specified fields
  • Get Employee Fields - Discover available fields and metadata
  • Create Employee - Add new employee (requires firstName, lastName minimum)
  • Update Employee - Modify employee information
  • Get Changed Employees - Get employees with recent data changes
  • Request Custom Employee Report - Generate custom reports with filters (supports JSON, CSV, PDF, XLS, XML)

Time Off Management (5 tools)​

  • Get Time Off Requests - List time off requests with filtering (date, status, employee, type)
  • Get Employee Time Off Policies - View assigned policies and current balances
  • Request Time Off - Submit time off request for approval
  • Get Who's Out - View current and upcoming absences
  • List Time Off Types - Get available time off types (vacation, sick, etc.)

Reports (3 tools)​

  • List Reports - Get available company reports
  • Get Report - Retrieve specific report by ID (multiple formats supported)
  • Get Changed Employee Table Data - Track changes to historical tables

Files & Documents (3 tools)​

  • Get Employee Files - List files and categories for an employee
  • List Employee File Categories - Get all file categories
  • Create Employee File Category - Add new file category for organization

Training & Performance (4 tools)​

  • Get Employee Training Records - List training courses and completion
  • Update Employee Training Record - Modify training details
  • Get Employee Goals - Retrieve performance goals
  • Create Employee Goal - Add new performance objective

Time Tracking (3 tools)​

  • Get Timesheet Entries - Retrieve timesheet data (beta feature, 365-day limit)
  • Add Timesheet Clock Entry - Clock employees in/out
  • Add Timesheet Hours - Create/update hour entries

Tables & History (2 tools)​

  • Get Employee Table Data - Retrieve historical table data (jobInfo, compensation, bonus, etc.)
  • List Employee Tables - Discover available historical data tables

Common Use Cases​

Employee Onboarding​

Create a new employee → Get employee fields to see what data is needed →
Update employee with additional details → Get employee to verify →
Create employee goals for the new hire

Time Off Management​

List time off types → Get employee time off policies to check balance →
Request time off → Get who's out to check team availability

Generating Custom Reports​

Get employee fields to discover available fields →
Request custom employee report with desired fields →
Export in preferred format (CSV, PDF, JSON, etc.)

Performance Reviews​

Get employee → Get employee goals to review progress →
Get employee training records to see completed courses →
Create employee goal for next review period

HR Data Synchronization​

Get changed employees since last sync →
For each changed employee: Get employee details →
Get changed table data for historical changes →
Update external HR systems

Team Availability Check​

Get who's out to see current absences →
Get time off requests for upcoming week →
Plan meetings and workload accordingly

Troubleshooting​

"Invalid company domain" error​

Cause: The company domain is formatted incorrectly or doesn't exist.

Solution:

  1. Use only the subdomain portion: mycompany (NOT https://mycompany.bamboohr.com or mycompany.bamboohr.com)
  2. Verify you're using the correct subdomain by checking your BambooHR login URL
  3. Make sure there are no extra spaces or special characters

"Invalid API key" error​

Cause: The API key is incorrect, expired, or has been deleted.

Solution:

  1. Verify you copied the complete API key value (they're long strings)
  2. Check that the key hasn't been deleted in BambooHR (User menu → API Keys)
  3. Generate a new API key and update Webrix
  4. Ensure there are no extra spaces when pasting the key

"Insufficient permissions" error​

Cause: The authenticated user doesn't have permission to access the requested resource.

Solution:

  1. Verify the user has appropriate permissions in BambooHR
  2. The API key has the same permissions as the user who generated it
  3. Contact your BambooHR administrator to grant necessary access levels

"Employee directory not found" error​

Cause: The company directory feature is disabled in BambooHR settings.

Solution:

  1. Use the Request Custom Employee Report tool instead - it's more reliable for bulk data retrieval
  2. Or have an administrator enable the company directory in BambooHR settings
  3. For specific employees, use Get Employee with the employee ID

Rate limit errors (503 Service Unavailable)​

Cause: Too many API requests in a short time period.

Solution:

  1. Wait a few minutes before retrying
  2. Reduce the frequency of requests
  3. Use bulk operations like custom reports instead of individual employee queries
  4. Implement exponential backoff for retries

"Field not found" error​

Cause: The requested field name doesn't exist or is misspelled.

Solution:

  1. Use the Get Employee Fields tool to discover available field names
  2. Check for typos in field names (they're case-sensitive)
  3. Custom fields may have different names than displayed in the UI
  4. Some fields may only be available in certain BambooHR plan levels

"Time tracking feature not available" error​

Cause: Time tracking is not enabled for your BambooHR account or is a beta feature with limited access.

Solution:

  1. Verify time tracking is enabled in your BambooHR account settings
  2. Note that time tracking APIs are in beta and may have limitations
  3. Check that you have permissions to view/edit timesheet data
  4. Time tracking data is limited to the last 365 days

Best Practices​

  1. Discover fields before querying - Use Get Employee Fields to understand available fields before building queries

  2. Use custom reports for bulk data - The Request Custom Employee Report tool is more reliable than the directory for retrieving multiple employees

  3. Check permissions - API operations are limited by the authenticated user's BambooHR permissions

  4. Handle historical data carefully - Fields like jobInfo, compensation, and bonuses are stored in tables with full history

  5. Monitor rate limits - Implement retry logic with exponential backoff for 503 errors

  6. Validate company domain - Ensure the company domain is correctly configured before troubleshooting other issues

  7. Store API keys securely - Never commit API keys to source control or share them publicly

  8. Use time off policies before requests - Check employee time off balances before submitting requests to avoid insufficient balance errors

  9. Test with sandbox/test data - If available, test integrations with non-production data first

Security Considerations​

  • Employee data is highly sensitive and subject to privacy regulations (GDPR, CCPA, etc.)
  • Operations that modify employee data (create, update) are marked as destructive
  • API keys have the same permissions as the user who generated them
  • API keys should be stored securely and never shared publicly
  • Access to compensation, benefits, and personal information should be restricted
  • Time tracking data may contain legally required records - handle with care
  • Regular audits of API access and data exports are recommended
  • Consider implementing additional access controls in your application layer
  • Be mindful of data retention policies when storing employee information externally

Additional Resources​