BambooHR Client

TypeScript client for BambooHR REST API.

Installation

npm install bamboohr-client

Usage

import { BambooHRClient } from 'bamboohr-client';

const client = new BambooHRClient({
  apiToken: process.env.BAMBOO_API_TOKEN,
  companyDomain: 'mycompany', // for mycompany.bamboohr.com
});

// Get employee directory
const directory = await client.employees.getDirectory();
console.log(`Found ${directory.employees.length} employees`);

// Get specific employee with fields
const employee = await client.employees.get({
  id: '123',
  fields: 'firstName,lastName,email,department,jobTitle',
});

// Get who's out
const whosOut = await client.timeOff.getWhosOut();

// Get time off requests
const requests = await client.timeOff.getRequests({
  start: '2025-01-01',
  end: '2025-12-31',
});

// Get employee time off balance
const balance = await client.timeOff.getBalance({
  employeeId: '123',
});

// Get employee goals
const goals = await client.goals.get({
  employeeId: '123',
  filter: 'open',
});

// List company files
const files = await client.files.list();

// Get all available fields
const fields = await client.meta.getFields();

API Structure

All methods are organized by domain:

| Domain | Methods | |--------|---------| | client.employees | get, getDirectory, getPhoto | | client.timeOff | getRequests, getBalance, getWhosOut | | client.goals | get | | client.files | list, get | | client.meta | getFields |

API Reference

| Domain | Method | Endpoint | |--------|--------|----------| | employees | get(params) | GET /employees/{id} | | employees | getDirectory() | GET /employees/directory | | employees | getPhoto(params) | GET /employees/{id}/photo/{size} | | timeOff | getRequests(params) | GET /time_off/requests | | timeOff | getBalance(params) | GET /employees/{id}/time_off/calculator | | timeOff | getWhosOut(params) | GET /time_off/whos_out | | goals | get(params) | GET /performance/employees/{id}/goals | | files | list() | GET /files/view | | files | get(params) | GET /files/{fileId} | | meta | getFields() | GET /meta/fields |

Authentication

Generate an API Key in BambooHR: Settings > API Keys > Add New Key

Set environment variables:

export BAMBOO_API_TOKEN=your-api-key
export BAMBOO_COMPANY_DOMAIN=yourcompany  # the subdomain part

Requirements

• Node.js >= 18.0.0

License

MIT