BambooHR Connector

Source npm · v0.2.0 API Docs API Changelog Connector Changelog

Description

BambooHR is a comprehensive human resources software platform that helps companies manage their HR processes effectively. BambooHR's services include an applicant tracking system, employee benefits tracker, time tracking, and employee records management. This component enables interaction with the BambooHR API.

API Documentation

This component was built using the BambooHR API Documentation.

Connections

API Key

key: apiKey

Authenticate requests to BambooHR using an API key.

Prerequisites

An active BambooHR account with permission to manage API keys.
The BambooHR company domain (the MYCOMPANY portion of https://MYCOMPANY.bamboohr.com).

Setup Steps

Log in to BambooHR.
Click the user profile image in the upper-right corner.
Select API Keys.
Click Add New Key.
Copy the generated key — it will be an approximately 40-character alphanumeric string. Store it securely; it will not be shown again.

Configure the Connection

Create a connection of type API Key and provide the following inputs:

API Key: The BambooHR API key generated in the steps above.
Company Domain: The MYCOMPANY portion of the https://MYCOMPANY.bamboohr.com instance URL.

Input	Notes	Example
API Key	The BambooHR API key used to authenticate requests. Generate this in the BambooHR account settings.
Company Domain	The MYCOMPANY portion of the https://MYCOMPANY.bamboohr.com instance URL.

Triggers

Changed Employees

Retrieves existing and ongoing employee changes from BambooHR. Load history once, check for changes on a schedule, or both. | key: pollChangesTrigger

Input	Notes	Example
Connection	The BambooHR connection to use.
Look-back Date	The date the initial sync starts from, in YYYY-MM-DD format. Cannot be a future date. Leave empty to start from the first recurrence with no backfill. When set, the initial sync seeds each record modified on or after this date once, ignoring the field and visibility filters.	2026-01-01
Show New Employees	When true, employees inserted since the last poll are included in the trigger output.	true
Show Updated Employees	When true, employees updated or deleted since the last poll are included in the trigger output. Inspect the `action` field on each record to distinguish updates from deletions.	true

This trigger retrieves existing and ongoing employee changes from BambooHR. Load history once, check for changes on a schedule, or both.

How It Works

On each scheduled recurrence, the trigger calls the BambooHR GET /v1/employees/changed endpoint with a since parameter set to the last poll time. The API returns a map of employee IDs to change actions. Each entry is classified as created when its action is Inserted, and otherwise as updated (covering both Updated and Deleted actions: inspect the action field to distinguish them).

Initial sync

An initial sync seeds a complete starting state rather than a change feed, so inputs that narrow which changes are reported would leave gaps: Show New Employees and Show Updated Employees are ignored while it runs, and are the only inputs it ignores. It begins on the first recurrence when the trigger has no stored position and a Look-back Date (YYYY-MM-DD) is set, and seeds every employee change on or after that date exactly once. Left empty, there is no sync and the trigger starts from its first recurrence.

The window has no fixed upper bound, so an employee change recorded mid-drain is swept into the sync. The trigger fetches the full window in a single recurrence regardless of whether batching is enabled. Once all matching changes have been emitted, the trigger stores the current time as its position and the first incremental recurrence resumes from exactly there. Without batching, all changes are returned in one payload. With batching, the resolver dispatches each record (or batch of records) as a separate execution within the same recurrence. Nothing in the payload marks the handoff.

The trigger has no page-size or field-selection input, so nothing else is suppressed.

Batching

Batching is enabled per flow on this trigger: each changed record is dispatched as its own execution, or grouped by the configured batch size. Batch size and batch concurrency can both be overridden per instance. Raising concurrency increases the request volume sent to BambooHR.

To turn it on, select the flow's trigger, open the Flow control tab, and switch on Enable Batching. Under Batch Size, keep Trigger default or choose Custom batch size. Batch Concurrency is optional; leave it blank for no batch-level limit.

With batching off, downstream steps read results.body.data.created and results.body.data.updated. With batching on, those fields do not exist. Each execution receives a single { changeType, record } object. Any step reading the older shape must be updated before batching is enabled. Because batching is enabled per flow, the change is scoped to that flow.

Returned Data

The trigger returns an object with two arrays: created for newly inserted employees and updated for updated or deleted employees. Fields shown are representative. The full response object includes additional properties.

Example Response

{
  "created": [
    {
      "id": "234",
      "action": "Inserted",
      "lastChanged": "2026-05-19T14:20:00+00:00"
    }
  ],
  "updated": [
    {
      "id": "5",
      "action": "Updated",
      "lastChanged": "2026-05-19T13:45:30+00:00"
    },
    {
      "id": "42",
      "action": "Deleted",
      "lastChanged": "2026-05-19T12:30:00+00:00"
    }
  ]
}

Batched Item Shape

When batching is enabled, each execution receives a single item:

{
  "changeType": "created",
  "record": {
    "id": "234",
    "action": "Inserted",
    "lastChanged": "2026-05-19T14:20:00+00:00"
  }
}

Example Payload for Changed Employees⤓

Loading…

Webhook

Receive and validate webhook requests from BambooHR for manually configured webhook subscriptions. | key: bamboohrTrigger

The BambooHR webhook trigger receives and validates incoming webhook requests from BambooHR. This trigger performs HMAC signature verification to ensure that payloads originate from BambooHR and have not been tampered with in transit.

For details on configuring webhooks in BambooHR, refer to the BambooHR Webhooks documentation.

How It Works

When BambooHR sends a webhook request, this trigger:

Extracts the x-bamboohr-signature and x-bamboohr-timestamp headers from the incoming request
Computes an HMAC-SHA256 hash using the request body concatenated with the timestamp and the stored signing secret
Compares the computed hash against the signature provided in the header
If the signatures match, the payload is accepted and passed to the flow for processing
If the signatures do not match, the request is rejected with an error

The signing secrets are stored in cross-flow state and may include multiple keys to support secret rotation.

Returned Data

Example Payload

{
  "headers": {
    "x-bamboohr-signature": "abc123def456...",
    "x-bamboohr-timestamp": "1700000000",
    "content-type": "application/json"
  },
  "body": {
    "data": {
      "employees": [
        {
          "id": "123",
          "action": "Updated",
          "changedFields": ["firstName", "lastName"]
        }
      ]
    }
  }
}

Notes

The trigger does not have configurable inputs. Webhook signing secrets are managed through cross-flow state.
Multiple signing secrets are supported, allowing for seamless secret rotation without downtime.
If none of the stored signing secrets produce a matching signature, the request is rejected to protect against unauthorized or tampered payloads.

Example Payload for Webhook⤓

Loading…

Data Sources

Select Company File

Select a company file from a list of company files. | key: selectCompanyFile | type: picklist

Input	Notes	Example
Connection	The BambooHR connection to use.

Example Payload for Select Company File⤓

Loading…

Select Employee

Select an employee from a list of employees. | key: selectEmployee | type: picklist

Input	Notes	Example
Connection	The BambooHR connection to use.

Select Employee File

Select an employee file from a list of files for the specified employee. | key: selectEmployeeFile | type: picklist

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42

Example Payload for Select Employee File⤓

Loading…

Actions

Add Employee Table Row

Add a row to the specified table for an employee. | key: addEmployeeTableRow

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42
Table Fields	The names of the fields and their values to use when creating/updating a row in a table. Use the "List Tabular Fields (Tables)" action to list possible field names for a table.
Table Name (Alias)	The alias of the BambooHR table to read or modify (for example, jobInfo, compensation, or employmentStatus).	jobInfo

Example Payload for Add Employee Table Row⤓

Loading…

Create Company File Category

Create a new company file category (folder). | key: addCompanyFileCategory

Input	Notes	Example
Category Name	The display name to assign to the new file category.	A new category
Connection	The BambooHR connection to use.

Example Payload for Create Company File Category⤓

Loading…

Create Employee

Create a new employee. | key: addEmployee

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee Fields	The names of the fields and their values to use when creating/updating a record. Possible fields are: address1, address2, age, bestEmail, birthday, city, country, dateOfBirth, department, division, employeeNumber, employmentHistoryStatus, ethnicity, exempt, firstName, fullName1, fullName2, fullName3, fullName4, fullName5, displayName, gender, hireDate, originalHireDate, id, jobTitle, lastChanged, lastName, location, maritalStatus, middleName, mobilePhone, nationality, payGroup, payRate, payRateEffectiveDate, payType, paidPer, paySchedule, payFrequency, includeInPayroll, timeTrackingEnabled, ssn, sin, standardHoursPerWeek, state, stateCode, status, supervisor, supervisorEmail, terminationDate, workEmail, workPhone, zipcode.
First Name	The given name of the employee being created.	John
Last Name	The family name of the employee being created.	Doe

Example Payload for Create Employee⤓

Loading…

Create Employee File Category

Create a new employee file category (folder). | key: addEmployeeFileCategory

Input	Notes	Example
Category Name	The display name to assign to the new file category.	A new category
Connection	The BambooHR connection to use.

Example Payload for Create Employee File Category⤓

Loading…

Create Webhook

Create a new webhook. | key: createWebhook

Input	Notes	Example
Allow Duplicates	When true, allows the creation of duplicate webhooks. By default this action checks if a webhook with this callback and sheet ID already exists and, if so, skips configuration.	false
Connection	The BambooHR connection to use.
Fields to Monitor	One or more fields to trigger this webhook on. This can be any of the following: firstName, lastName, hireDate, department, middleName, dateOfBirth, ssn, address1, address2, city, state, zipcode, mobilePhone, homePhone, workEmail, jobTitle, location, gender, maritalStatus, payType, eeo, status, workPhone, workPhoneExtension, employeeNumber, ethnicity, division, homeEmail, preferredName, employeeStatusDate, country, payChangeReason, payRateEffectiveDate, exempt, twitterFeed, facebook, linkedIn, pinterest, acaStatus, payPer, originalHireDate, paySchedule, instagram, allergies, dietaryRestrictions, hoursPerPayCycle.
Webhook Name	A descriptive label used to identify the webhook in BambooHR.	New Hire Notifications
Fields to Send to Webhook	The list of fields to include in the payload posted to the callback URL. This can be any of the following: firstName, lastName, hireDate, department, middleName, dateOfBirth, ssn, address1, address2, city, state, zipcode, mobilePhone, homePhone, workEmail, jobTitle, location, gender, maritalStatus, payType, eeo, status, workPhone, workPhoneExtension, employeeNumber, ethnicity, division, homeEmail, preferredName, employeeStatusDate, country, payChangeReason, payRateEffectiveDate, exempt, twitterFeed, facebook, linkedIn, pinterest, acaStatus, payPer, originalHireDate, paySchedule, instagram, allergies, dietaryRestrictions, hoursPerPayCycle.
Callback URL	The URL where BambooHR should send webhook payloads.	https://example.com/webhook

Example Payload for Create Webhook⤓

Loading…

Delete Company File

Delete a company file. | key: deleteCompanyFile

Input	Notes	Example
Connection	The BambooHR connection to use.
File ID	The unique identifier for the company file.	456

Example Payload for Delete Company File⤓

Loading…

Delete Employee File

Delete an employee file. | key: deleteEmployeeFile

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee File ID	The unique identifier for the employee file.	456
Employee ID	The unique identifier for the employee.	42

Example Payload for Delete Employee File⤓

Loading…

Delete Instance Webhooks

Delete all BambooHR webhooks that point to a flow in this instance. | key: deleteInstanceWebhooks

Input	Notes	Example
Connection	The BambooHR connection to use.

Example Payload for Delete Instance Webhooks⤓

Loading…

Delete Webhook

Delete a webhook by ID. | key: deleteWebhookById

Input	Notes	Example
Connection	The BambooHR connection to use.
Webhook ID	The unique identifier for the webhook.	789

Example Payload for Delete Webhook⤓

Loading…

Get Company File

Retrieve a company file. | key: getCompanyFile

Input	Notes	Example
Connection	The BambooHR connection to use.
File ID	The unique identifier for the company file.	456

Example Payload for Get Company File⤓

Loading…

Get Employee

Retrieve an employee by ID. | key: getEmployee

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42

Example Payload for Get Employee⤓

Loading…

Get Employee File

Retrieve an employee file. | key: getEmployeeFile

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee File ID	The unique identifier for the employee file.	456
Employee ID	The unique identifier for the employee.	42

Example Payload for Get Employee File⤓

Loading…

Get Employee Table

Retrieve a specific table associated with an employee. | key: getEmployeeTable

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42
Table Name (Alias)	The alias of the BambooHR table to read or modify (for example, jobInfo, compensation, or employmentStatus).	jobInfo

Example Payload for Get Employee Table⤓

Loading…

List Company Files

List all company file categories and files. | key: listCompanyFiles

Input	Notes	Example
Connection	The BambooHR connection to use.

Example Payload for List Company Files⤓

Loading…

List Employee Files

List all employee file categories and files. | key: listEmployeeFiles

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42

Example Payload for List Employee Files⤓

Loading…

List Employees

List all employees from the directory. | key: getEmployeeDirectory

Input	Notes	Example
Connection	The BambooHR connection to use.

Example Payload for List Employees⤓

Loading…

List Tabular Fields

List all tables and their fields in the account. | key: getTabularFields

Input	Notes	Example
Connection	The BambooHR connection to use.

Example Payload for List Tabular Fields⤓

Loading…

List Time Off Requests

List employee time off requests for a given date range. | key: getTimeOffRequests

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42
End Date	The last date of the time off range to query or create. Format: YYYY-MM-DD.	2024-01-31
Start Date	The first date of the time off range to query or create. Format: YYYY-MM-DD.	2024-01-01
Time Off Record ID	The unique identifier for a specific time off request record.	42
Status	The time off request status to filter by.

Example Payload for List Time Off Requests⤓

Loading…

List Webhooks

List all existing webhooks. | key: listWebhooks

Input	Notes	Example
Connection	The BambooHR connection to use.
Show Only Instance Webhooks	When true, only webhooks that point to this instance are returned.	true

Example Payload for List Webhooks⤓

Loading…

List Who's Out

List all employees currently taking time off. | key: whosOut

Input	Notes	Example
Connection	The BambooHR connection to use.
End Date	The last date of the range to query. Defaults to 14 days from the start date if omitted. Format: YYYY-MM-DD.	2024-01-15
Start Date	The first date of the range to query. Defaults to today's date if omitted. Format: YYYY-MM-DD.	2024-01-01

Example Payload for List Who's Out⤓

Loading…

Raw Request

Send a raw HTTP request to BambooHR. | key: rawRequest

Input	Notes	Example
Connection	The BambooHR connection to use.
Data	The HTTP body payload to send to the URL.	{"exampleKey": "Example Data"}
File Data	File Data to be sent as a multipart form upload.	[{key: "example.txt", value: "My File Contents"}]
File Data File Names	File names to apply to the file data inputs. Keys must match the file data keys above.
Form Data	The Form Data to be sent as a multipart form upload.	[{"key": "Example Key", "value": new Buffer("Hello World")}]
Header	A list of headers to send with the request.	User-Agent: curl/7.64.1
Max Retry Count	The maximum number of retries to attempt. Specify 0 for no retries.	0
Method	The HTTP method to use.
Query Parameter	A list of query parameters to send with the request. This is the portion at the end of the URL similar to ?key1=value1&key2=value2.
Response Type	The type of data you expect in the response. You can request json, text, or binary data.	json
Retry On All Errors	If true, retries on all erroneous responses regardless of type. This is helpful when retrying after HTTP 429 or other 3xx or 4xx errors. Otherwise, only retries on HTTP 5xx and network errors.	false
Retry Delay (ms)	The delay in milliseconds between retries. This is used when 'Use Exponential Backoff' is disabled.	0
Timeout	The maximum time that a client will await a response to its request	2000
URL	Input the path only (/v1/employees/directory), The base URL is already included (https://api.bamboohr.com/api/gateway.php/COMPANY_DOMAIN). For example, to connect to https://api.bamboohr.com/api/gateway.php/COMPANY_DOMAIN/v1/employees/directory, only /v1/employees/directory is entered in this field.	/v1/employees/directory
Use Exponential Backoff	Specifies whether to use a pre-defined exponential backoff strategy for retries. When enabled, 'Retry Delay (ms)' is ignored.	false

Example Payload for Raw Request⤓

Loading…

Update Employee

Update an existing employee. | key: updateEmployee

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee Fields	The names of the fields and their values to use when creating/updating a record. Possible fields are: address1, address2, age, bestEmail, birthday, city, country, dateOfBirth, department, division, employeeNumber, employmentHistoryStatus, ethnicity, exempt, firstName, fullName1, fullName2, fullName3, fullName4, fullName5, displayName, gender, hireDate, originalHireDate, id, jobTitle, lastChanged, lastName, location, maritalStatus, middleName, mobilePhone, nationality, payGroup, payRate, payRateEffectiveDate, payType, paidPer, paySchedule, payFrequency, includeInPayroll, timeTrackingEnabled, ssn, sin, standardHoursPerWeek, state, stateCode, status, supervisor, supervisorEmail, terminationDate, workEmail, workPhone, zipcode.
Employee ID	The unique identifier for the employee.	42

Example Payload for Update Employee⤓

Loading…

Update Employee Table Row

Update a specific row in an employee table. | key: updateEmployeeTableRow

Input	Notes	Example
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42
Row ID	The unique identifier for the row in the table.	123
Table Fields	The names of the fields and their values to use when creating/updating a row in a table. Use the "List Tabular Fields (Tables)" action to list possible field names for a table.
Table Name (Alias)	The alias of the BambooHR table to read or modify (for example, jobInfo, compensation, or employmentStatus).	jobInfo

Example Payload for Update Employee Table Row⤓

Loading…

Upload Company File

Upload a new company file. | key: uploadCompanyFile

Input	Notes	Example
Category ID	The unique identifier for the file category.	20
Connection	The BambooHR connection to use.
File Contents	The binary contents of the file to upload, typically referenced from a previous step.
File Name	The name to assign to the uploaded file, including its extension.	example.pdf
Share	When true, the file is shared with the employee.	false

Example Payload for Upload Company File⤓

Loading…

Upload Employee File

Upload a new employee file. | key: uploadEmployeeFile

Input	Notes	Example
Category ID	The unique identifier for the file category.	20
Connection	The BambooHR connection to use.
Employee ID	The unique identifier for the employee.	42
File Contents	The binary contents of the file to upload, typically referenced from a previous step.
File Name	The name to assign to the uploaded file, including its extension.	example.pdf
Share	When true, the file is shared with the employee.	false

Example Payload for Upload Employee File⤓

Loading…

Changelog

2026-11-05

Updated to the latest spectral

2026-11-03

Published the component as an npm package, so code-native integrations can install it and call its actions, triggers and data sources from code with TypeScript types

2026-10-20

Added large data sync support to the Changed Employees trigger:

Added opt-in batching to the Changed Employees trigger, dispatching each changed record individually or in configured batches; enabling it changes the shape a downstream step receives
Added an optional Look-back Date input for performing an initial sync of employees. The initial sync begins on the first recurrence and backfills every employee changed on or after the specified date, seeding each once and ignoring the trigger's filters; later recurrences are unaffected. Leave it empty to start from the first recurrence with no backfill

2026-07-27

Enhanced multiple actions to return more informative API responses:

Updated Upload Employee File and Upload Company File actions to return the Location header from the API response
Updated Create Employee action to return the employee id and Location header from the API response
Updated Add Employee Table Row action to return a descriptive success message instead of an empty response
Updated Create Employee File Category and Create Company File Category actions to return status-based success messages reflecting the API response code

2026-05-26

Added Changed Employees polling trigger to detect new, updated, and deleted employees in BambooHR on a configured schedule

2026-04-30

Updated spectral version

2026-04-07

Added trigger documentation and global debug support across all actions for improved troubleshooting

2026-03-31

Various modernizations and documentation updates

2026-03-24

Added Employee File ID inline data source input to Delete Employee File and Get Employee File actions for selecting employee files from a dropdown

2026-02-26

Added inline data sources for company files and employee files to enhance file selection capabilities

2025-11-19

Enhanced webhook triggers to support simulated test executions

2025-01-03

Added data sources and inline data sources for employees

BambooHR Connector

Description​

API Documentation​

Connections​

API Key​

Prerequisites​

Setup Steps​

Configure the Connection​

Triggers​

Changed Employees​

How It Works​

Returned Data​

Webhook​

How It Works​

Returned Data​

Notes​

Data Sources​

Select Company File​

Select Employee​

Select Employee File​

Actions​

Add Employee Table Row​

Create Company File Category​

Create Employee​

Create Employee File Category​

Create Webhook​

Delete Company File​

Delete Employee File​

Delete Instance Webhooks​

Delete Webhook​

Get Company File​

Get Employee​

Get Employee File​

Get Employee Table​

List Company Files​

List Employee Files​

List Employees​

List Tabular Fields​

List Time Off Requests​

List Webhooks​

List Who's Out​

Raw Request​

Update Employee​

Update Employee Table Row​

Upload Company File​

Upload Employee File​

Changelog​

2026-11-05​

2026-11-03​

2026-10-20​

2026-07-27​

2026-05-26​

2026-04-30​

2026-04-07​

2026-03-31​

2026-03-24​

2026-02-26​

2025-11-19​

2025-01-03​

Description

API Documentation

Connections

API Key

Prerequisites

Setup Steps

Configure the Connection

Triggers

Changed Employees

How It Works

Returned Data

Webhook

How It Works

Returned Data

Notes

Data Sources

Select Company File

Select Employee

Select Employee File

Actions

Add Employee Table Row

Create Company File Category

Create Employee

Create Employee File Category

Create Webhook

Delete Company File

Delete Employee File

Delete Instance Webhooks

Delete Webhook

Get Company File

Get Employee

Get Employee File

Get Employee Table

List Company Files

List Employee Files

List Employees

List Tabular Fields

List Time Off Requests

List Webhooks

List Who's Out

Raw Request

Update Employee

Update Employee Table Row

Upload Company File

Upload Employee File

Changelog

2026-11-05

2026-11-03

2026-10-20

2026-07-27

2026-05-26

2026-04-30

2026-04-07

2026-03-31

2026-03-24

2026-02-26

2025-11-19

2025-01-03