Angela is building a remote-first recruiting platform called Benchmark. She has three engineers, a head of sales, and 47 clients — staffing agencies and tech startups who use Benchmark to manage candidate pipelines and hiring workflows. Angela's newest feature is post-hire onboarding: when a candidate accepts an offer, Benchmark should automatically create the employee record in the client's HR system, generate onboarding tasks, and track completion. Eleven of Angela's clients use BambooHR. The first client to test the integration is a 60-person SaaS company that hires two to three engineers per month. Angela tells Ralph to connect to the client's BambooHR instance, read the current employee directory, and create a new employee record when a hire is confirmed. Angela has a product demo with a prospect at 1 PM and a board update call at 5. The BambooHR integration cannot consume her morning. ```typescript import { Contact, Company } from '@headlessly/crm' import { Task, Project } from '@headlessly/projects' const onboarding = await Project.create({ name: 'Engineering Onboarding — March 2026', status: 'active' }) await Contact.create({ name: 'Dana Kowalski', email: 'dana@clientco.com', company: 'company_nR7kV3wQp', department: 'Engineering', role: 'Senior Backend Engineer', startDate: '2026-03-10' }) await Task.create({ title: 'Provision GitHub access', project: onboarding.$id, assignee: 'contact_hP3mV8xLw', priority: 'high' }) ``` ## Ralph Opens the BambooHR API Ralph is Angela's ops agent. He is thorough — he reads the full API surface before writing a single call. The client provided their BambooHR subdomain (`clientco.bamboohr.com`) and an API key generated from BambooHR's settings panel. Ralph navigates to `documentation.bamboohr.com` and begins mapping available endpoints. Authentication is straightforward: BambooHR uses HTTP Basic Auth with the API key as the username and `x` as the password. Ralph requests the employee directory: ```bash GET https://api.bamboohr.com/api/gateway.php/clientco/v1/employees/directory Authorization: Basic {base64(api_key:x)} Accept: application/json ``` The `Accept: application/json` header is critical. BambooHR's API returns XML by default. Without the JSON header, Ralph receives: ```xml

Display name First name Last name Job title Department Division Work Email Work Phone Photo URL

Rachel Torres Rachel Torres VP of Engineering Engineering ``` An API built in 2026 that defaults to XML. Ralph adds the `Accept` header and gets JSON — but the JSON structure mirrors the XML exactly, with fields as an array of `{id, value}` pairs rather than a flat key-value object: ```json { "employees": [ { "id": "114", "displayName": "Rachel Torres", "firstName": "Rachel", "lastName": "Torres", "jobTitle": "VP of Engineering", "department": "Engineering", "workEmail": "rachel@clientco.com" } ] } ``` The directory endpoint returns a fixed set of fields. It does not include hire date, employment status, compensation, manager, or custom fields. To get a complete employee record, Ralph must call the individual employee endpoint with specific field names: ```bash GET https://api.bamboohr.com/api/gateway.php/clientco/v1/employees/114?fields=firstName,lastName,workEmail,hireDate,status,department,jobTitle,supervisor,customField1,customField2 Authorization: Basic {base64(api_key:x)} Accept: application/json