Bamboozled wraps the BambooHR API without the use of Rails dependencies.
Latest commit 96b837a Apr 5, 2017 @enriikke enriikke Merge pull request #32 from nlively/time-tracking
add time tracking api interface

Gem Version Build Status Code Climate Coverage Status Inline Docs


Bamboozled is a Ruby wrapper for the BambooHR API.


Bamboozled follows Semantic Versioning 2.0.0. Make sure to always bound the major version when installing if you want to avoid breaking changes.


This documentation tracks the latest changes in the master branch of this repo. Some of the features described might not be available in older versions of the gem (including the current stable version). Please consult the relevant git tag (e.g. v0.0.7) if you need documentation for a specific Bamboozled version.


Bamboozled's installation follows the standard gem installation process:

$ gem install bamboozled

If you prefer to install Bamboozled through bundler then add it to your Gemfile:

gem "bamboozled"


Create a client and provide it with your BambooHR subdomain and an API key:

# Create the client:
client = Bamboozled.client(subdomain: "your_subdomain", api_key: "your_api_key")

TIP! Create an API key by logging into your BambooHR account, then click your image in the upper right corner and select "API Keys".

Employee related data:

You can pass an array of fields to all or :all to get all fields your user is allowed to access. Because BambooHR's API doesn't allow for specifying fields on the /employees/directory API endpoint, passing a list of fields to retrieve will be signifigantly slower than getting just the default fields since the gem will get the directory of employees, then request the data for each individual employee resulting in employees.count + 1 API calls.

# Returns an array of all employees
client.employee.all # Gets all employees with default fields
client.employee.all(:all) # Gets all fields for all employees
client.employee.all(["hireDate", "displayName"])

# Get the employee records which have changed since a given date
client.employee.last_changed("2015-01-01T00:00:00-08:00", :updated)
client.employee.last_changed("2015-01-01T00:00:00-08:00", :inserted)
client.employee.last_changed("2015-01-01T00:00:00-08:00", :deleted)
client.employee.last_changed("2015-01-01T00:00:00-08:00") # Return all changes

# Returns a hash of a single employee
client.employee.find(employee_id, fields = nil)

# Adds an employee

# Tabular employee data

# Time off estimate for employee. Requires end date in Date or Time format or YY-MM-DD string.
client.employee.time_off_estimate(employee_id, end_date)

# Photos for an employee

Time off data

# Get time off requests filtered by a number of parameters
# :id - the ID of the time off request
# :action -
# :employeeId - the ID of the employee you're looking for
# :start - filter start date
# :end - filter end date
# :type - type of time off request
# :status - must be one or more of the following: approved denied superceded requested canceled
client.time_off.requests(:employeeId: employee_id, start:

# See who is out when.
client.time_off.whos_out(, "2014-12-31")


# Find a report by its number, format = "JSON", fd = true)


# Get fields
# Get lists
# Get tables
# Get users
# Note: this is all uses in the system, whereas client.employee.all only gets active employees


Thank you for contributing! We always welcome bug reports and/or pull requests. Please take the time to go through our contribution guidelines.

Special thanks to all the awesome people who have helped make this gem better. You can see a list of them here.


This project is licensed under the terms of the MIT license. See the LICENSE file.