Claude Code skill pack for BambooHR (18 skills)

18 plugin-local skills

MIT License

Claude Code Adapters (declared)

Installation

Open Claude Code and run this command:

/plugin install bamboohr-pack@claude-code-plugins-plus

Use --global to install for all projects, or --project for current project only.

What It Does

> 18 Claude Code skills for building production BambooHR API integrations — employee management, time off, webhooks, and HR data pipelines.

Build real BambooHR integrations with real API endpoints (api.bamboohr.com/api/gateway.php/{company}/v1/), real employee fields, real webhook HMAC verification, and real error handling. Every skill uses the actual BambooHR REST API — no fake SDKs or placeholder code.

Skills (18) plugin-local skills

bamboohr-ci-integration View full skill →

Configure CI/CD pipelines for BambooHR integrations with GitHub Actions, automated testing, and secret management.

ReadWriteEditBash(gh:*)

BambooHR CI Integration

Overview

Set up CI/CD pipelines for BambooHR integrations with proper secret management, unit tests with mocked API, and optional integration tests against the real BambooHR API.

Prerequisites

GitHub repository with Actions enabled
BambooHR test API key (sandbox company or test account)
npm/pnpm project with test suite configured

Instructions

Step 1: Configure GitHub Secrets


# Required for integration tests
gh secret set BAMBOOHR_API_KEY --body "your-test-api-key"
gh secret set BAMBOOHR_COMPANY_DOMAIN --body "your-test-company"

# Optional: webhook testing
gh secret set BAMBOOHR_WEBHOOK_SECRET --body "your-webhook-hmac-secret"

Step 2: GitHub Actions Workflow


# .github/workflows/bamboohr-integration.yml
name: BambooHR Integration

on:
  push:
    branches: [main]
  pull_request:
    branches: [main]
  schedule:
    # Run daily to catch BambooHR API changes early
    - cron: '0 6 * * 1-5'

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - run: npm run typecheck
      - name: Unit tests (mocked BambooHR API)
        run: npm test -- --coverage --reporter=verbose
      - uses: actions/upload-artifact@v4
        if: always()
        with:
          name: coverage
          path: coverage/

  integration-tests:
    runs-on: ubuntu-latest
    # Only run on main branch and schedule (not PRs from forks)
    if: github.event_name != 'pull_request' || github.event.pull_request.head.repo.full_name == github.repository
    needs: unit-tests
    env:
      BAMBOOHR_API_KEY: ${{ secrets.BAMBOOHR_API_KEY }}
      BAMBOOHR_COMPANY_DOMAIN: ${{ secrets.BAMBOOHR_COMPANY_DOMAIN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
          cache: 'npm'
      - run: npm ci
      - name: Integration tests (real BambooHR API)
        run: npm run test:integration
        timeout-minutes: 5
      - name: API health check
        run: |
          STATUS=$(curl -s -o /dev/null -w "%{http_code}" \
            -u "${BAMBOOHR_API_KEY}:x" \
            -H "Accept: application/json" \
            "https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1/employees/directory")
          echo "BambooHR API status: $STATUS"
          [ "$STATUS" -eq 200 ] || exit 1

Step 3: Test Structure


// tests/unit/bamboohr-client.test.ts
import { describe, it, expect, beforeAll, afterAll, afterEach } from 'vitest';
import { setupServe…

bamboohr-common-errors View full skill →

Diagnose and fix BambooHR API errors and exceptions.

ReadGrepBash(curl:*)

BambooHR Common Errors

Overview

Diagnostic reference for BambooHR REST API errors. BambooHR returns error details in the X-BambooHR-Error-Message response header for most 400-level and some 500-level errors.

Prerequisites

BambooHR API access configured
Access to application logs or HTTP response headers

Instructions

Step 1: Read the Error Header

Always check X-BambooHR-Error-Message first — it contains BambooHR's specific error detail, which is more useful than generic HTTP status text.


const res = await fetch(`${BASE}/employees/999/`, {
  headers: { Authorization: AUTH, Accept: 'application/json' },
});

if (!res.ok) {
  const errorDetail = res.headers.get('X-BambooHR-Error-Message');
  console.error(`HTTP ${res.status}: ${errorDetail || res.statusText}`);
}

Step 2: Match Error to Solution

401 Unauthorized — Invalid API Key


X-BambooHR-Error-Message: Invalid API key

Cause: API key is missing, expired, revoked, or malformed in the Basic Auth header.

Solution:


# Verify key is set
echo "Key length: ${#BAMBOOHR_API_KEY}"

# Test auth directly
curl -s -o /dev/null -w "%{http_code}" \
  -u "${BAMBOOHR_API_KEY}:x" \
  "https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1/employees/directory"

Common mistakes:

Using Bearer token instead of Basic Auth
Putting the API key as the password instead of the username
Missing the :x password part in Basic Auth encoding

403 Forbidden — Insufficient Permissions


X-BambooHR-Error-Message: You do not have access to this resource

Cause: The API key's user account lacks permissions for the requested endpoint or employee.

Solution:

Verify the user's access level in BambooHR (Account > Access Levels)
Time-off management endpoints require manager or admin permissions
Compensation table access requires admin permissions
Some fields are restricted to specific access levels

400 Bad Request — Invalid Fields or Payload


X-BambooHR-Error-Message: Invalid field: "jobTitl"

Cause: Misspelled field name, invalid date format, or malformed JSON body.

Solution:


# Verify field names against BambooHR's field list
curl -s -u "${BAMBOOHR_API_KEY}:x" \
  "https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1/employees/0/?fields=firstName,lastName" \
  -H "Accept: appli…

bamboohr-core-workflow-a View full skill →

Execute BambooHR primary workflows: employee CRUD, directory sync, and custom reports.

ReadWriteEditBash(curl:*)Grep

BambooHR Core Workflow A — Employee Management & Reports

Overview

Primary BambooHR workflows: CRUD operations on employees, directory sync to external systems, custom reports, and table data (job history, compensation, emergency contacts).

Prerequisites

Completed bamboohr-install-auth setup
BambooHRClient from bamboohr-sdk-patterns
API key with appropriate permissions (read or read+write)

Instructions

Step 1: Add a New Employee


// POST /employees/ — minimum: firstName + lastName
const newEmpRes = await fetch(`${BASE}/employees/`, {
  method: 'POST',
  headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    firstName: 'Sarah',
    lastName: 'Chen',
    department: 'Engineering',
    jobTitle: 'Backend Engineer',
    workEmail: 'sarah.chen@acmecorp.com',
    hireDate: '2026-04-01',
    location: 'San Francisco',
    status: 'Active',
  }),
});

// New employee ID is in the Location header
const locationHeader = newEmpRes.headers.get('Location');
// e.g., "https://api.bamboohr.com/.../v1/employees/456"
const newId = locationHeader?.split('/').pop();
console.log(`Created employee ID: ${newId}`);

Step 2: Update Employee Fields


// POST /employees/{id}/ — only send fields you want to change
await fetch(`${BASE}/employees/${newId}/`, {
  method: 'POST',
  headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    jobTitle: 'Senior Backend Engineer',
    department: 'Platform Engineering',
  }),
});

Fields that trigger position history changes: jobTitle, department, division, location, reportsTo. Updating these creates a new row in the employee's position history table.

Step 3: Directory Sync to External System


interface SyncResult {
  created: number;
  updated: number;
  deactivated: number;
  errors: string[];
}

async function syncBambooHRDirectory(
  onSync: (emp: BambooEmployee, action: string) => Promise<void>,
): Promise<SyncResult> {
  const result: SyncResult = { created: 0, updated: 0, deactivated: 0, errors: [] };

  // Fetch full directory
  const { employees } = await client.getDirectory();

  // Use the "changed since" endpoint for incremental sync
  // GET /employees/changed/?since=2026-03-20T00:00:00Z
  const changedRes = await client.request<Record<string, { lastChanged: string }>>(
    'GET', `/employees/changed/?since=${lastSyncTimestamp}`,
  );

  for (const [empId, meta] of…

bamboohr-core-workflow-b View full skill →

Execute BambooHR secondary workflows: time off requests, PTO balances, benefits administration, and employee files/photos.

ReadWriteEditBash(curl:*)Grep

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-DD
const 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}`);
}

Time off request response shape:


[
  {
    "id": "100",
    "employeeId": "123",
    "status": { "status": "approved", "lastChanged": "2026-03-15" },
    "name": "Jane Smith",
    "start": "2026-03-20",
    "end": "2026-03-22",
    "type": { "id": "1", "name": "Vacation" },
    "amount": { "unit": "days", "amount": "3" },
    "notes": { "employee": "Spring break trip", "manager": "" },
    "dates": {
      "2026-03-20": "1", "2026-03-21": "1", "2026-03-22": "1"
    }
  }
]

Step 2: Create a Time Off Request


// PUT /employees/{id}/time_off/request
await fetch(`${BASE}/employees/123/time_off/request`, {
  method: 'PUT',
  headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
  body: JSON.stringify({
    status: 'requested',
    start: '2026-04-15',
    end: '2026-04-18',
    timeOffTypeId: 1, // 1 = Vacation, varies by company
    amount: 4,
    notes: { employee: 'Family vacation' },
    dates: {
      '2026-04-15': '1',
      '2026-04-16': '1',
      '2026-04-17': '1',
      '2026-04-18': '1',
    },
    previousRequest: 0,
  }),
});

Step 3: Approve or Deny a Request


// PUT /time_off/requests/{requestId}/status
await fetch(`${BASE}/time_off/requests/100/status`, {
  method: 'PUT',
  headers: { Authorization: AUTH, 'Content-Type': 'application/json' },
  body: JSON.stringify({…

bamboohr-cost-tuning View full skill →

Optimize BambooHR integration costs through request reduction, caching, and usage monitoring.

ReadGrep

BambooHR Cost Tuning

Overview

BambooHR pricing is per-employee-per-month (not per-API-call), but excessive API usage triggers rate limiting (503 errors) which causes sync failures and operational issues. This skill covers reducing API call volume, monitoring usage, and building efficient sync patterns.

Prerequisites

BambooHR integration in production
Understanding of current API usage patterns
Application logging capturing API calls

Instructions

Step 1: Understand BambooHR Pricing

BambooHR charges by employee count, not API calls:

Plan	Pricing Model	API Access
Essentials	Per employee/month	Full REST API
Advantage	Per employee/month	Full REST API + advanced reports
Custom/Enterprise	Negotiated	Full API + dedicated support

Key insight: API call volume does not directly affect your bill, but hitting rate limits causes operational failures. Optimize for reliability, not cost.

Step 2: Audit Current API Usage


// Instrument your client to log all API calls
class InstrumentedBambooHRClient {
  private callLog: { endpoint: string; method: string; timestamp: number; durationMs: number }[] = [];

  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
    const start = Date.now();
    const result = await this.innerClient.request<T>(method, path, body);
    this.callLog.push({
      endpoint: path.split('?')[0], // Strip query params
      method,
      timestamp: start,
      durationMs: Date.now() - start,
    });
    return result;
  }

  generateReport(): void {
    // Group by endpoint
    const byEndpoint = new Map<string, number>();
    for (const call of this.callLog) {
      const key = `${call.method} ${call.endpoint}`;
      byEndpoint.set(key, (byEndpoint.get(key) || 0) + 1);
    }

    console.log('\n=== BambooHR API Usage Report ===');
    console.log(`Total calls: ${this.callLog.length}`);
    console.log(`Time window: ${((Date.now() - this.callLog[0]?.timestamp || 0) / 1000 / 60).toFixed(1)} minutes`);
    console.log('\nBy endpoint:');
    for (const [endpoint, count] of [...byEndpoint.entries()].sort((a, b) => b[1] - a[1])) {
      const pct = ((count / this.callLog.length) * 100).toFixed(1);
      console.log(`  ${count.toString().padStart(5)} (${pct}%)  ${endpoint}`);
    }
  }
}

Step 3: Eliminate Wasteful Patterns

Pattern 1: Replace polling with webhooks


// BAD: Polling every 5 minutes (288 calls/day minimum)
setInterval(async () => {
  const dir = await client.getDirectory();
  checkForChanges…

bamboohr-debug-bundle View full skill →

Collect BambooHR debug evidence for support tickets and troubleshooting.

ReadBash(curl:*)Bash(tar:*)Bash(node:*)Grep

BambooHR Debug Bundle

Overview

Collect all diagnostic information for BambooHR API troubleshooting or support tickets. Captures connectivity tests, API response details, environment info, and redacted configuration.

Prerequisites

BambooHR environment variables set
curl available for API tests
Permission to collect environment info

Instructions

Step 1: Complete Debug Bundle Script


#!/bin/bash
# bamboohr-debug-bundle.sh — Run this, then send the .tar.gz to support

set -euo pipefail

BUNDLE_DIR="bamboohr-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE_DIR"

DOMAIN="${BAMBOOHR_COMPANY_DOMAIN:?Set BAMBOOHR_COMPANY_DOMAIN}"
API_KEY="${BAMBOOHR_API_KEY:?Set BAMBOOHR_API_KEY}"
BASE="https://api.bamboohr.com/api/gateway.php/${DOMAIN}/v1"

exec > >(tee "$BUNDLE_DIR/summary.txt") 2>&1

echo "=== BambooHR Debug Bundle ==="
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)"
echo "Company Domain: ${DOMAIN}"
echo "API Key: ${API_KEY:0:4}****${API_KEY: -4}"
echo ""

# ── Environment ──────────────────────────────────────
echo "--- Runtime Environment ---"
echo "Node.js: $(node --version 2>/dev/null || echo 'not installed')"
echo "npm: $(npm --version 2>/dev/null || echo 'not installed')"
echo "Python: $(python3 --version 2>/dev/null || echo 'not installed')"
echo "curl: $(curl --version 2>/dev/null | head -1)"
echo "OS: $(uname -a)"
echo ""

# ── API Connectivity Test ────────────────────────────
echo "--- API Connectivity ---"
echo -n "Directory endpoint: "
curl -s -o "$BUNDLE_DIR/directory-response.json" \
  -w "HTTP %{http_code} | %{time_total}s | %{size_download} bytes\n" \
  -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/employees/directory"

echo -n "Employee endpoint: "
curl -s -o "$BUNDLE_DIR/employee-response.json" \
  -w "HTTP %{http_code} | %{time_total}s | %{size_download} bytes\n" \
  -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/employees/0/?fields=firstName"

echo -n "Time off types: "
curl -s -o "$BUNDLE_DIR/timeoff-types-response.json" \
  -w "HTTP %{http_code} | %{time_total}s\n" \
  -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/meta/time_off/types"

echo ""

# ── Response Headers (verbose for one endpoint) ─────
echo "--- Response Headers (directory) ---"
curl -s -I -u "${API_KEY}:x" \
  -H "Accept: application/json" \
  "${BASE}/employees/directory" \
  | grep -iE "^(x-bamboohr|co…

bamboohr-deploy-integration View full skill →

Deploy BambooHR integrations to Vercel, Fly.

ReadWriteEditBash(vercel:*)Bash(fly:*)Bash(gcloud:*)

BambooHR Deploy Integration

Overview

Deploy BambooHR-powered applications to cloud platforms with proper secrets management, health checks, and webhook endpoint configuration. Covers Vercel (serverless), Fly.io (containers), and Google Cloud Run.

Prerequisites

BambooHR integration tested locally and in staging
Production API key and company domain ready
Platform CLI installed (vercel, fly, or gcloud)

Instructions

Vercel Deployment (Serverless)


# Set BambooHR secrets in Vercel
vercel env add BAMBOOHR_API_KEY production
vercel env add BAMBOOHR_COMPANY_DOMAIN production
vercel env add BAMBOOHR_WEBHOOK_SECRET production

vercel.json:


{
  "functions": {
    "api/**/*.ts": {
      "maxDuration": 30
    }
  },
  "crons": [{
    "path": "/api/bamboohr/sync",
    "schedule": "0 */6 * * *"
  }]
}

Webhook endpoint (Vercel serverless):


// api/webhooks/bamboohr.ts
import { verifyBambooHRWebhook } from '../../src/bamboohr/security';

export const config = { api: { bodyParser: false } };

export default async function handler(req: any, res: any) {
  if (req.method !== 'POST') return res.status(405).end();

  const chunks: Buffer[] = [];
  for await (const chunk of req) chunks.push(chunk);
  const rawBody = Buffer.concat(chunks);

  const sig = req.headers['x-bamboohr-signature'];
  const ts = req.headers['x-bamboohr-timestamp'];

  if (!verifyBambooHRWebhook(rawBody, sig, ts, process.env.BAMBOOHR_WEBHOOK_SECRET!)) {
    return res.status(401).json({ error: 'Invalid signature' });
  }

  const event = JSON.parse(rawBody.toString());
  // Process webhook asynchronously
  await processWebhookEvent(event);

  return res.status(200).json({ received: true });
}

Deploy:


vercel --prod
# Webhook URL: https://your-app.vercel.app/api/webhooks/bamboohr

Fly.io Deployment (Containers)

fly.toml:


app = "my-bamboohr-sync"
primary_region = "iad"

[env]
  NODE_ENV = "production"

[http_service]
  internal_port = 3000
  force_https = true
  auto_stop_machines = "suspend"
  auto_start_machines = true
  min_machines_running = 1

[[services.http_checks]]
  interval = "30s"
  timeout = "5s"
  path = "/api/health"
  method = "GET"


# Set secrets
fly secrets set BAMBOOHR_API_KEY="your-prod-key"
fly secrets set BAMBOOHR_COMPANY_DOMAIN="yourcompany"
fly secrets set BAMBOOHR_WEBHOOK_SECR…

bamboohr-hello-world View full skill →

Create a minimal working BambooHR example — fetch employee directory and single employee.

ReadWriteEditBash(curl:*)

BambooHR Hello World

Overview

Minimal working examples for the three most common BambooHR API operations: fetch the employee directory, get a single employee by ID, and run a custom report.

Prerequisites

Completed bamboohr-install-auth setup
BAMBOOHR_API_KEY and BAMBOOHR_COMPANY_DOMAIN env vars set

Instructions

Step 1: Fetch Employee Directory


import 'dotenv/config';

const COMPANY = process.env.BAMBOOHR_COMPANY_DOMAIN!;
const API_KEY = process.env.BAMBOOHR_API_KEY!;
const BASE = `https://api.bamboohr.com/api/gateway.php/${COMPANY}/v1`;
const AUTH = `Basic ${Buffer.from(`${API_KEY}:x`).toString('base64')}`;

// GET /employees/directory — returns all active employees
const dirRes = await fetch(`${BASE}/employees/directory`, {
  headers: { Authorization: AUTH, Accept: 'application/json' },
});
const directory = await dirRes.json();

console.log(`Company has ${directory.employees.length} employees`);
for (const emp of directory.employees.slice(0, 5)) {
  console.log(`  ${emp.displayName} — ${emp.jobTitle} (${emp.department})`);
}

Directory response shape:


{
  "fields": [
    { "id": "displayName", "type": "text", "name": "Display Name" },
    { "id": "jobTitle", "type": "text", "name": "Job Title" }
  ],
  "employees": [
    {
      "id": "123",
      "displayName": "Jane Smith",
      "firstName": "Jane",
      "lastName": "Smith",
      "jobTitle": "Software Engineer",
      "department": "Engineering",
      "location": "Remote",
      "workEmail": "jane@acme.com",
      "photoUrl": "https://..."
    }
  ]
}

Step 2: Get a Single Employee


// GET /employees/{id}/?fields=firstName,lastName,jobTitle,department,hireDate,workEmail
const empRes = await fetch(
  `${BASE}/employees/123/?fields=firstName,lastName,jobTitle,department,hireDate,workEmail,status`,
  { headers: { Authorization: AUTH, Accept: 'application/json' } },
);
const employee = await empRes.json();

console.log(`${employee.firstName} ${employee.lastName}`);
console.log(`  Title: ${employee.jobTitle}`);
console.log(`  Dept:  ${employee.department}`);
console.log(`  Hired: ${employee.hireDate}`);
console.log(`  Email: ${employee.workEmail}`);

Common employee fields you can request:

Field	Description
`firstName`, `last…`

bamboohr-install-auth View full skill →

Install and configure BambooHR API authentication with HTTP Basic Auth.

ReadWriteEditBash(npm:*)Bash(pip:*)Bash(curl:*)Grep

BambooHR Install & Auth

Overview

Set up BambooHR REST API authentication. BambooHR uses HTTP Basic Authentication — your API key is the username, and the password can be any arbitrary string (typically x).

Base URL pattern:


https://api.bamboohr.com/api/gateway.php/{companyDomain}/v1/

Where {companyDomain} is your BambooHR subdomain (e.g., acmecorp from acmecorp.bamboohr.com).

Prerequisites

Node.js 18+ or Python 3.10+
BambooHR account with API access enabled
API key generated from BambooHR (Account > API Keys)
Company subdomain from your BambooHR URL

Instructions

Step 1: Generate an API Key

Log in to BambooHR at https://{companyDomain}.bamboohr.com
Click your profile icon > API Keys
Click Add New Key, give it a descriptive name
Copy the key immediately — it is only shown once

Step 2: Configure Environment Variables


# Required
export BAMBOOHR_API_KEY="your-api-key-here"
export BAMBOOHR_COMPANY_DOMAIN="yourcompany"

# Create .env file for local development
cat > .env << 'EOF'
BAMBOOHR_API_KEY=your-api-key-here
BAMBOOHR_COMPANY_DOMAIN=yourcompany
EOF

# IMPORTANT: Add to .gitignore
echo '.env' >> .gitignore
echo '.env.local' >> .gitignore

Step 3: Install HTTP Client


# Node.js — no BambooHR-specific SDK needed; use fetch or axios
npm install dotenv

# Python
pip install requests python-dotenv

Step 4: Verify Connection

TypeScript / Node.js:


import 'dotenv/config';

const COMPANY = process.env.BAMBOOHR_COMPANY_DOMAIN!;
const API_KEY = process.env.BAMBOOHR_API_KEY!;
const BASE_URL = `https://api.bamboohr.com/api/gateway.php/${COMPANY}/v1`;

// BambooHR uses HTTP Basic Auth: API key as username, "x" as password
const headers = {
  'Authorization': `Basic ${Buffer.from(`${API_KEY}:x`).toString('base64')}`,
  'Accept': 'application/json',
};

// Test: fetch the employee directory
const res = await fetch(`${BASE_URL}/employees/directory`, { headers });

if (res.ok) {
  const data = await res.json();
  console.log(`Connected. ${data.employees?.length ?? 0} employees found.`);
} else {
  console.error(`Auth failed: ${res.status} ${res.statusText}`);
  const errHeader = res.headers.get('X-BambooHR-Error-Message');
  if (errHeader) console.error(`Detail: ${errHeader}`);
}

Python:


import os, requests
from dotenv import load_dotenv

load_dotenv()

COMPANY = os.environ["BAMBOOHR_COMP…

bamboohr-local-dev-loop View full skill →

Configure BambooHR local development with hot reload, mocking, and testing.

ReadWriteEditBash(npm:*)Bash(pnpm:*)Grep

BambooHR Local Dev Loop

Overview

Set up a fast, reproducible local development workflow for BambooHR integrations with request mocking, hot reload, and integration testing against the real API.

Prerequisites

Completed bamboohr-install-auth setup
Node.js 18+ with npm or pnpm
BAMBOOHR_API_KEY and BAMBOOHR_COMPANY_DOMAIN set in .env

Instructions

Step 1: Project Structure


my-bamboohr-project/
├── src/
│   ├── bamboohr/
│   │   ├── client.ts       # Reusable API client
│   │   ├── types.ts         # BambooHR response types
│   │   └── employees.ts     # Employee operations
│   └── index.ts
├── tests/
│   ├── mocks/
│   │   └── bamboohr.ts      # API response fixtures
│   ├── unit/
│   │   └── employees.test.ts
│   └── integration/
│       └── bamboohr.test.ts
├── .env.local               # Real API key (git-ignored)
├── .env.example              # Template for team
├── .env.test                 # Test config (sandbox key)
└── package.json

Step 2: Create Reusable API Client


// src/bamboohr/client.ts
import 'dotenv/config';

export class BambooHRClient {
  private baseUrl: string;
  private authHeader: string;

  constructor(companyDomain?: string, apiKey?: string) {
    const domain = companyDomain || process.env.BAMBOOHR_COMPANY_DOMAIN!;
    const key = apiKey || process.env.BAMBOOHR_API_KEY!;
    this.baseUrl = `https://api.bamboohr.com/api/gateway.php/${domain}/v1`;
    this.authHeader = `Basic ${Buffer.from(`${key}:x`).toString('base64')}`;
  }

  async request<T>(path: string, options: RequestInit = {}): Promise<T> {
    const res = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        Authorization: this.authHeader,
        Accept: 'application/json',
        'Content-Type': 'application/json',
        ...options.headers,
      },
    });

    if (!res.ok) {
      const errMsg = res.headers.get('X-BambooHR-Error-Message') || res.statusText;
      throw new BambooHRError(res.status, errMsg, path);
    }

    return res.json() as Promise<T>;
  }

  async getEmployee(id: number | string, fields: string[]): Promise<Record<string, string>> {
    return this.request(`/employees/${id}/?fields=${fields.join(',')}`);
  }

  async getDirectory(): Promise<{ employees: BambooEmployee[] }> {
    return this.request('/employees/directory');
  }
}

export class BambooHRError extends Error {
  constructor(public status: number, message: string, public path: string) {
    super(`BambooHR ${status}: ${message} [${path}]`);
    this.name = 'BambooHRError';
  }
}

Step 3: Setup Hot Reload and Scripts


{
  "scripts": {
    "dev": "tsx wa…

bamboohr-performance-tuning View full skill →

Optimize BambooHR API performance with caching, batch reports, incremental sync, and connection pooling.

ReadWriteEdit

BambooHR Performance Tuning

Overview

Optimize BambooHR API performance through request reduction, caching, incremental sync, and connection pooling. The biggest wins come from eliminating N+1 query patterns using custom reports and the changed-since endpoint.

Prerequisites

BambooHR API client configured
Redis or in-memory cache available (optional)
Performance monitoring in place

Instructions

Step 1: Eliminate N+1 Queries with Custom Reports

The single biggest performance improvement: use POST /reports/custom instead of individual employee GETs.


// BAD: 501 API calls for 500 employees
const dir = await client.getDirectory();                      // 1 call
for (const emp of dir.employees) {
  await client.getEmployee(emp.id, ['salary', 'hireDate']);   // 500 calls
}

// GOOD: 1 API call for all employees with all needed fields
const report = await client.customReport([
  'firstName', 'lastName', 'department', 'jobTitle',
  'hireDate', 'workEmail', 'status', 'location',
  'supervisor', 'employeeNumber',
]);
// 1 call, returns all employees with all fields

Performance impact: 500x reduction in API calls. Custom reports return all active employees in one request.

Step 2: Incremental Sync with Changed-Since


import { readFileSync, writeFileSync } from 'fs';

const LAST_SYNC_FILE = '.bamboohr-last-sync';

async function incrementalSync(client: BambooHRClient): Promise<string[]> {
  // Read last sync timestamp
  let lastSync: string;
  try {
    lastSync = readFileSync(LAST_SYNC_FILE, 'utf-8').trim();
  } catch {
    lastSync = new Date(Date.now() - 24 * 60 * 60 * 1000).toISOString(); // Default: 24h ago
  }

  // GET /employees/changed/?since=... — returns only changed employee IDs
  const changed = await client.request<{
    employees: Record<string, { id: string; lastChanged: string }>;
  }>('GET', `/employees/changed/?since=${lastSync}`);

  const changedIds = Object.keys(changed.employees || {});
  console.log(`${changedIds.length} employees changed since ${lastSync}`);

  if (changedIds.length === 0) return [];

  // Fetch only changed employees' details
  // For large sets, use custom report with filter; for small sets, individual GETs
  if (changedIds.length > 20) {
    // Bulk: use custom report (returns all, then filter client-side)
    const report = await client.customReport([
      'firstName', 'lastName', 'department', 'status',
    ]);
    const changedData = report.employees.filter(e =>
      changedIds.includes(e.id?.toString()),
    );
    // Process changedData...
  } else {
    // Small set: individual GETs are fi…

bamboohr-prod-checklist View full skill →

Execute BambooHR production deployment checklist and rollback procedures.

ReadBash(kubectl:*)Bash(curl:*)Grep

BambooHR Production Checklist

Overview

Complete pre-launch checklist for deploying BambooHR integrations to production, covering API configuration, data integrity, monitoring, and rollback procedures.

Prerequisites

Staging environment tested and verified
Production BambooHR API key ready
Deployment pipeline configured
Monitoring and alerting infrastructure available

Instructions

Pre-Deployment Checklist

Authentication & Secrets

[ ] Production API key created under a service account (not personal account)
[ ] API key stored in secrets manager (AWS Secrets Manager / GCP Secret Manager / Vault)
[ ] BAMBOOHR_COMPANY_DOMAIN set correctly for production
[ ] Webhook secret stored securely
[ ] Key rotation procedure documented and tested
[ ] Old staging/test keys will not be deployed to production

API Integration Quality

[ ] All API calls use Accept: application/json header
[ ] Error handling covers all BambooHR HTTP statuses (400, 401, 403, 404, 503)
[ ] X-BambooHR-Error-Message header parsed for error details
[ ] Retry-After header honored on 503 responses
[ ] Exponential backoff with jitter implemented for retries
[ ] Request queue limits concurrent API calls (max 3-5 parallel)
[ ] No hardcoded employee IDs, company domains, or API keys

Data Integrity

[ ] Custom reports validated against expected field schema
[ ] Employee directory sync handles new, updated, and terminated employees
[ ] Date fields parsed consistently (YYYY-MM-DD format)
[ ] Null/empty field handling tested (BambooHR returns null or "")
[ ] Unicode employee names handled correctly
[ ] Large directory tested (500+ employees)

Security & Compliance

[ ] PII fields redacted from application logs
[ ] Webhook signatures verified with HMAC-SHA256
[ ] Only necessary BambooHR fields requested (least data principle)
[ ] No SSN, salary, or restricted data stored without encryption at rest
[ ] API access audit trail enabled

Health Check Endpoint


// api/health.ts
import { BambooHRClient, BambooHRApiError } from '../bamboohr/client';

interface HealthStatus {
  status: 'healthy' | 'degraded' | 'down';
  bamboohr: {
    connected: boolean;
    latencyMs: number;
    error?: string;
    employeeCount?: number;
  };
  timestamp: string;
}

export async function healthCheck(client: BambooHRClient): Promise<HealthStatus> {
  const start = Date.now();
  try {
    const dir = await client.getDirectory();
    return {
…

bamboohr-rate-limits View full skill →

Implement BambooHR rate limiting, backoff, and request optimization.

ReadWriteEdit

BambooHR Rate Limits

Overview

BambooHR does not publish exact rate limits, but the API returns 503 Service Unavailable with a Retry-After header when you exceed them. This skill covers detection, backoff, request optimization, and queue-based throttling.

Prerequisites

BambooHR API client configured
Understanding of async/await patterns

Instructions

Step 1: Understand BambooHR Rate Limiting Behavior

BambooHR rate limiting details:

Signal	Value	Description
HTTP Status	`503`	Primary rate limit signal
`Retry-After` header	seconds (e.g., `30`)	How long to wait before retrying
`X-BambooHR-Error-Message`	varies	May contain rate limit detail
HTTP Status `429`	rare	Some endpoints return 429 for employee count limits

Key insight: BambooHR uses 503 (not 429) for rate limiting. Failed authentication attempts also count toward rate limits, so ensure your API key is valid before making many requests.

Step 2: Implement Retry-After Aware Backoff


import { BambooHRApiError } from './client';

interface RetryConfig {
  maxRetries: number;
  baseDelayMs: number;
  maxDelayMs: number;
}

const DEFAULT_RETRY: RetryConfig = {
  maxRetries: 5,
  baseDelayMs: 1000,
  maxDelayMs: 60_000,
};

async function withBambooHRRetry<T>(
  operation: () => Promise<T>,
  config = DEFAULT_RETRY,
): Promise<T> {
  for (let attempt = 0; attempt <= config.maxRetries; attempt++) {
    try {
      return await operation();
    } catch (err) {
      if (attempt === config.maxRetries) throw err;
      if (!(err instanceof BambooHRApiError)) throw err;
      if (!err.retryable) throw err; // Only retry 429, 503, 500, 502

      // Honor BambooHR's Retry-After header
      let delay: number;
      if (err.meta.retryAfter) {
        delay = parseInt(err.meta.retryAfter, 10) * 1000;
      } else {
        // Exponential backoff with jitter
        const exponential = config.baseDelayMs * Math.pow(2, attempt);
        const jitter = Math.random() * config.baseDelayMs;
        delay = Math.min(exponential + jitter, config.maxDelayMs);
      }

      console.warn(
        `BambooHR rate limited (attempt ${attempt + 1}/${config.maxRetries}). ` +
        `Waiting ${(delay / 1000).toFixed(1)}s...`
      );
      await new Promise(r => setTimeout(r, delay));
    }
  }
  throw new Error('unreachable');
}

Step 3: Queue-Based Rate Limiting


import PQueue from 'p-queue';

// BambooHR unoffici…

bamboohr-reference-architecture View full skill →

Implement BambooHR reference architecture for production HR data pipelines.

ReadGrep

BambooHR Reference Architecture

Overview

Production-ready architecture for BambooHR integrations covering the three most common patterns: real-time employee sync, HR data pipeline, and employee lifecycle automation.

Prerequisites

Understanding of layered architecture and event-driven design
BambooHR API knowledge from earlier skills in this pack
TypeScript project setup with Node.js 18+

Instructions

Architecture Overview


┌──────────────────────────────────────────────────────────┐
│                    Your Application                       │
├──────────────┬───────────────┬────────────────────────────┤
│  API Layer   │  Sync Engine  │  Webhook Handler           │
│  /api/*      │  (Cron/Queue) │  /webhooks/bamboohr        │
├──────────────┴───────────────┴────────────────────────────┤
│                   Service Layer                            │
│  EmployeeService  │  TimeOffService  │  ReportService     │
├───────────────────┴──────────────────┴────────────────────┤
│                BambooHR Client Layer                       │
│  BambooHRClient  │  Cache  │  RetryHandler  │  Metrics    │
├───────────────────┴─────────┴────────────────┴────────────┤
│                   Data Layer                               │
│  PostgreSQL (employees)  │  Redis (cache)  │  S3 (files)  │
└───────────────────────────────────────────────────────────┘
                           │
                           ▼
              ┌────────────────────────┐
              │   BambooHR REST API    │
              │ api.bamboohr.com/api/  │
              │   gateway.php/{co}/v1  │
              └────────────────────────┘

Project Structure


bamboohr-integration/
├── src/
│   ├── bamboohr/
│   │   ├── client.ts              # HTTP client (from sdk-patterns)
│   │   ├── types.ts               # BambooHR API response types
│   │   ├── retry.ts               # Retry with Retry-After support
│   │   ├── cache.ts               # LRU + Redis cache layer
│   │   └── metrics.ts             # Request counting and latency
│   ├── services/
│   │   ├── employee-sync.ts       # Incremental directory sync
│   │   ├── time-off.ts            # PTO balance and request management
│   │   ├── reports.ts             # Custom report generation
│   │   └── lifecycle.ts           # Onboarding/offboarding automation
│   ├── handlers/
│   │   ├── webhook.ts             # Webhook signature verification + routing
│   │   └── events.ts              # Employee change event processors
│   ├── api/
│   │   ├── health.ts              # Health check endpoint
│   │   ├── employees.ts           # REST API for local employee data
│   │   └── reports.ts             # Report generation endpoints
│   ├── jobs/
│   │   ├── full-sync.ts           # Scheduled full directory sync
│   │   ├── incremental-sync.ts    # Frequent delta sync
│   │   └── report-export.ts       …

bamboohr-sdk-patterns View full skill →

Apply production-ready BambooHR API patterns for TypeScript and Python.

ReadWriteEdit

BambooHR SDK Patterns

Overview

Production-ready patterns for the BambooHR REST API. BambooHR has no official Node.js SDK — you call the API directly via fetch or axios. These patterns wrap the raw HTTP calls into type-safe, retry-aware, multi-tenant-ready code.

Prerequisites

Completed bamboohr-install-auth setup
Familiarity with async/await and TypeScript generics

Instructions

Step 1: Type-Safe Client with Error Handling


// src/bamboohr/client.ts
import 'dotenv/config';

export interface BambooHRConfig {
  companyDomain: string;
  apiKey: string;
  timeoutMs?: number;
}

export interface BambooEmployee {
  id: string;
  firstName: string;
  lastName: string;
  displayName: string;
  jobTitle: string;
  department: string;
  division: string;
  workEmail: string;
  location: string;
  status: string;
  hireDate: string;
  supervisor: string;
  employeeNumber: string;
  photoUrl?: string;
}

export class BambooHRClient {
  private base: string;
  private auth: string;
  private timeout: number;

  constructor(config: BambooHRConfig) {
    this.base = `https://api.bamboohr.com/api/gateway.php/${config.companyDomain}/v1`;
    this.auth = `Basic ${Buffer.from(`${config.apiKey}:x`).toString('base64')}`;
    this.timeout = config.timeoutMs ?? 30_000;
  }

  async request<T>(method: string, path: string, body?: unknown): Promise<T> {
    const controller = new AbortController();
    const timer = setTimeout(() => controller.abort(), this.timeout);

    try {
      const res = await fetch(`${this.base}${path}`, {
        method,
        headers: {
          Authorization: this.auth,
          Accept: 'application/json',
          ...(body ? { 'Content-Type': 'application/json' } : {}),
        },
        body: body ? JSON.stringify(body) : undefined,
        signal: controller.signal,
      });

      if (!res.ok) {
        const errMsg = res.headers.get('X-BambooHR-Error-Message') || res.statusText;
        throw new BambooHRApiError(res.status, errMsg, path, {
          retryAfter: res.headers.get('Retry-After'),
        });
      }

      // Some endpoints return 200 with no body (e.g., PUT updates)
      const text = await res.text();
      return text ? JSON.parse(text) : ({} as T);
    } finally {
      clearTimeout(timer);
    }
  }

  // ── Employee endpoints ────────────────────────────────
  async getEmployee(id: number | string, fields: string[]) {
    return this.request<Record<string, string>>('GET', `/employees/${id}/?fields=${fields.join(',')}`);
  }

  async getDirectory() {
    return this.request<{ fields: any[]; employees: BambooEmployee[] }>('GET', '/employees/directory');
  }

  async addEmployee(data: { firstName: string; lastName: string; [k: strin…

bamboohr-security-basics View full skill →

Apply BambooHR security best practices for API keys, webhook verification, and PII data handling compliance.

ReadWriteGrep

BambooHR Security Basics

Overview

Security best practices for BambooHR API integrations covering API key management, webhook HMAC verification, PII handling, and access control. BambooHR contains highly sensitive employee data (SSNs, salaries, addresses) — treat every integration as PII-critical.

Prerequisites

BambooHR API access configured
Understanding of environment variables and secrets management
Access to BambooHR admin settings

Instructions

Step 1: API Key Security


# .env (NEVER commit to git)
BAMBOOHR_API_KEY=your-api-key
BAMBOOHR_COMPANY_DOMAIN=yourcompany
BAMBOOHR_WEBHOOK_SECRET=your-webhook-hmac-secret

# .gitignore — MUST include these
.env
.env.local
.env.*.local
*.pem

Key management rules:

Each environment (dev/staging/prod) uses a separate API key
Create API keys under service accounts, not personal accounts
API keys inherit the permissions of the user who created them
Rotate keys quarterly; immediately rotate if exposed

Key rotation procedure:


# 1. Generate new key in BambooHR: Profile > API Keys > Add New Key
# 2. Update secret store
aws secretsmanager update-secret --secret-id bamboohr/api-key --secret-string "new-key"
# Or for GCP:
echo -n "new-key" | gcloud secrets versions add bamboohr-api-key --data-file=-

# 3. Deploy with new key
# 4. Verify new key works
curl -s -o /dev/null -w "%{http_code}" \
  -u "new-key:x" \
  "https://api.bamboohr.com/api/gateway.php/${DOMAIN}/v1/employees/directory" \
  -H "Accept: application/json"

# 5. Delete old key in BambooHR dashboard

Step 2: Webhook Signature Verification

BambooHR signs webhook payloads with SHA-256 HMAC. Verify every webhook before processing.


import crypto from 'crypto';

function verifyBambooHRWebhook(
  rawBody: Buffer | string,
  signature: string,
  timestamp: string,
  secret: string,
): boolean {
  // 1. Reject old timestamps (replay attack protection — 5 min window)
  const age = Date.now() - parseInt(timestamp, 10) * 1000;
  if (age > 300_000 || age < -60_000) {
    console.error(`Webhook timestamp outside 5-minute window: ${age}ms`);
    return false;
  }

  // 2. Compute expected HMAC
  const payload = `${timestamp}.${rawBody.toString()}`;
  const expected = crypto
    .createHmac('sha256', secret)
    .update(payload)
    .digest('hex');

  // 3. Timing-safe comparison (prevents timing attacks)
  try {
    return crypto.timingSafeEqual(
      Buffer.from(signature, 'hex'),
      Buffer.from(expected, 'hex'),
    );
  } catch {
    return false;
  }
}

// Express middleware
app.post('/webhooks/bamboohr',
  express.…

bamboohr-upgrade-migration View full skill →

Plan and execute BambooHR API migration with breaking change detection.

ReadWriteEditBash(npm:*)Bash(git:*)

BambooHR Upgrade & Migration

Overview

Guide for handling BambooHR API changes, migrating from legacy patterns, and proactively detecting deprecations. BambooHR's API is versioned at v1 — breaking changes are announced on their changelog rather than through version bumps.

Prerequisites

Current BambooHR integration working
Access to BambooHR API changelog
Git for version control
Test suite available

Instructions

Step 1: Check for Announced Changes


# Monitor BambooHR's official changelog pages
echo "Check these URLs before any migration work:"
echo "  Past changes:    https://documentation.bamboohr.com/docs/past-changes-to-the-api"
echo "  Planned changes: https://documentation.bamboohr.com/docs/planned-changes-to-the-api"
echo "  Status page:     https://status.bamboohr.com"

Step 2: Common Migration Patterns

URL Format Migration

BambooHR has used two base URL formats historically:


// Legacy format (still works)
const LEGACY = `https://api.bamboohr.com/api/gateway.php/${domain}/v1`;

// Modern format (equivalent)
const MODERN = `https://${domain}.bamboohr.com/api/v1`;

// Migration: both work, but use the gateway.php format for API key auth
// The modern format is used for browser-based OAuth flows

XML to JSON Migration


// Legacy: XML responses (default if no Accept header)
const xmlRes = await fetch(`${BASE}/employees/directory`, {
  headers: { Authorization: AUTH },
  // No Accept header — returns XML
});

// Current: JSON responses (always set Accept header)
const jsonRes = await fetch(`${BASE}/employees/directory`, {
  headers: { Authorization: AUTH, Accept: 'application/json' },
});

// Migration checklist:
// - Add 'Accept: application/json' to ALL requests
// - Replace XML parsing with JSON.parse
// - Update response type definitions

Employee Endpoint Changes


// Legacy: using employee ID 0 for "current user"
// GET /employees/0/?fields=firstName,lastName
// This returns the employee record for the API key's user

// Current: still works, but prefer explicit employee IDs from directory
const dir = await client.getDirectory();
const currentUser = dir.employees.find(e => e.workEmail === knownEmail);

Step 3: Detect Deprecated Field Usage


// Scan your codebase for BambooHR field references
const DEPRECATED_FIELDS = [
  // As of 2025, these field aliases may change:
  'bestEmail',       // Use 'workEmail' or 'homeEmail' explicitly
  'fullName1',       // Use 'displayName' instead
  'fullName2',       // Use firstName + lastName
  '…

bamboohr-webhooks-events View full skill →

Implement BambooHR webhook endpoints with HMAC signature validation and employee change event handling.

ReadWriteEditBash(curl:*)

BambooHR Webhooks & Events

Overview

BambooHR supports two webhook types: global webhooks (configured in the BambooHR admin UI, subset of fields) and permissioned webhooks (created via API, access all fields the API key user can see). This skill covers creating, validating, and handling both types.

Prerequisites

BambooHR API key with webhook management permissions
HTTPS endpoint accessible from the internet
Webhook secret for HMAC-SHA256 signature verification

Instructions

Step 1: Understand Webhook Types

Feature	Global Webhooks	Permissioned Webhooks
Setup	BambooHR admin UI	API (`POST /webhooks/`)
Field access	Subset of standard fields	All fields user can access
Auth	Shared secret	Per-webhook secret
Signature	SHA-256 HMAC	SHA-256 HMAC
Actions	Created, Updated, Deleted	Created, Updated, Deleted

Step 2: Create a Permissioned Webhook via API


// POST /webhooks/ — register a new webhook
const webhook = await client.request<{
  id: number;
  name: string;
  privateKey: string; // Save this — used for HMAC verification
}>('POST', '/webhooks/', {
  name: 'Employee Sync Webhook',
  monitorFields: [
    'firstName', 'lastName', 'jobTitle', 'department',
    'division', 'location', 'workEmail', 'status',
    'supervisor', 'hireDate', 'terminationDate',
  ],
  postFields: {
    firstName: 'firstName',
    lastName: 'lastName',
    jobTitle: 'jobTitle',
    department: 'department',
    status: 'status',
    workEmail: 'workEmail',
  },
  url: 'https://your-app.example.com/webhooks/bamboohr',
  format: 'json',
  frequency: { every: 0 }, // 0 = immediate, or N = batch every N minutes
  limit: { enabled: false },
});

console.log(`Webhook ID: ${webhook.id}`);
console.log(`Private Key: ${webhook.privateKey}`);
// IMPORTANT: Store the privateKey securely — it's the HMAC secret

Step 3: List and Manage Webhooks


// GET /webhooks/ — list all webhooks for this API key
const webhooks = await client.request<any[]>('GET', '/webhooks/');
for (const wh of webhooks) {
  console.log(`${wh.id}: ${wh.name} -> ${wh.url} (${wh.status})`);
}

// GET /webhooks/{id}/ — get webhook details
const detail = await client.request<any>('GET', `/webhooks/${webhook.id}/`);

// GET /webhooks/{id}/log — get webhook delivery logs
const logs = await client…

How It Works


export BAMBOOHR_API_KEY="your-key"
export BAMBOOHR_COMPANY_DOMAIN="yourcompany"

curl -s -u "${BAMBOOHR_API_KEY}:x" \
  "https://api.bamboohr.com/api/gateway.php/${BAMBOOHR_COMPANY_DOMAIN}/v1/employees/directory" \
  -H "Accept: application/json" | head -c 200

Then ask Claude: "Help me sync BambooHR employees to my database" and the relevant skills activate automatically.