bamboohr-upgrade-migration

name	bamboohr-upgrade-migration
description	Plan and execute BambooHR API migration with breaking change detection. Use when BambooHR announces API changes, adapting to deprecated endpoints, or migrating from legacy API patterns to current best practices. Trigger with phrases like "upgrade bamboohr", "bamboohr migration", "bamboohr breaking changes", "bamboohr API update", "bamboohr deprecated".
allowed-tools	Read, Write, Edit, Bash(npm:*), Bash(git:*)
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","hr","bamboohr","migration"]
compatible-with	claude-code

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: { :  },
  
});


 jsonRes =  (, {
  : { : , :  },
});