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)
• [ ] BAMBOOHRCOMPANYDOMAIN 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 {
      status: 'health

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:

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 unofficial guidance: s

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       # Scheduled re

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: string]: string }) 

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.raw({ type: &#

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
  'fullName3',       

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

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.request<any[]&