BambooHR

An Elixir client for the Bamboo HR API.

Installation

The package can be installed by adding bamboo_hr to your list of dependencies in mix.exs:

def deps do
  [
    {:bamboo_hr, "~> 0.4.0"}
  ]
end

Usage

To use this client, you'll need information from BambooHR:

• Your company's subdomain
• An API key

API Structure

The library is organized into several modules, each representing different API resources:

• BambooHR.Client - Core client functionality and configuration
• BambooHR.Company - Company information and EINs
• BambooHR.Employee - Employee management
• BambooHR.Metadata - Field, tabular, and list field metadata
• BambooHR.TimeTracking - Time entries and timesheets

Examples

Getting Started

First, create a client configuration:

config = BambooHR.Client.new(company_domain: "your_company", api_key: "your_api_key")

You can also specify optional parameters:

config = BambooHR.Client.new(
  company_domain: "your_company",
  api_key: "your_api_key",
  base_url: "https://custom-api.example.com",
  http_client: YourCustomHTTPClient,
  timeout: 30_000
)

Company Information

# Get basic company information
{:ok, company_info} = BambooHR.Company.get_information(config)

# Get company EINs
{:ok, eins_data} = BambooHR.Company.get_eins(config)

Employee Management

# Get employee directory
{:ok, directory} = BambooHR.Employee.get_directory(config)

# Get specific employee details
{:ok, employee} = BambooHR.Employee.get(config, 123, ["firstName", "lastName", "jobTitle"])

# Add a new employee
employee_data = %{"firstName" => "Jane", "lastName" => "Smith"}
{:ok, result} = BambooHR.Employee.add(config, employee_data)

# Update an employee
update_data = %{"firstName" => "Jane", "lastName" => "Smith-Jones"}
{:ok, _} = BambooHR.Employee.update(config, 124, update_data)

Field Metadata

# List all employee fields (id, name, type)
{:ok, %{"fields" => fields}} = BambooHR.Metadata.get_fields(config)

# List tabular fields (employment history, compensation, etc.)
{:ok, %{"tabularFields" => tabular}} = BambooHR.Metadata.get_tabular_fields(config)

# List list fields and their option values (departments, divisions, etc.)
{:ok, %{"items" => lists}} = BambooHR.Metadata.get_lists(config)

Time Tracking

# Get timesheet entries
params = %{
  "start" => "2024-01-01",
  "end" => "2024-01-31",
  "employeeIds" => "123,124"
}
{:ok, timesheet_data} = BambooHR.TimeTracking.get_timesheet_entries(config, params)

# Clock in an employee
clock_data = %{
  "date" => "2024-01-15",
  "start" => "09:00",
  "timezone" => "America/New_York"
}
{:ok, _} = BambooHR.TimeTracking.clock_in(config, 123, clock_data)

# Clock out an employee
clock_out_data = %{
  "date" => "2024-01-15",
  "end" => "17:00",
  "timezone" => "America/New_York"
}
{:ok, _} = BambooHR.TimeTracking.clock_out(config, 123, clock_out_data)

Development

Requirements

• Elixir 1.17+ / Erlang/OTP 25+ (see .tool-versions for exact versions used locally)
• Homebrew (macOS/Linux) for dev tooling

Setup

Install dependencies and git hooks:

./bin/setup
mix setup

./bin/setup installs actionlint, check-jsonschema, and mado via Homebrew. mix setup then fetches Elixir dependencies and activates the pre-commit hooks via git_hoox.

Common commands

mix test                        # Run tests
mix format                      # Format code
mix credo --strict              # Static analysis
mix dialyzer                    # Type analysis (PLT cached under priv/plts/)
mix docs                        # Generate documentation
mix deps.unlock --check-unused  # Check for unused dependencies

Pre-commit hooks

Hooks run automatically on git commit (configured in .git_hoox.exs):

Inspect the resolved config with mix git_hoox.list or validate it with mix git_hoox.doctor.

License

BambooHR is released under the MIT license.