> For the complete documentation index, see [llms.txt](https://docs.coupler.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.coupler.io/sources/category/project-management/bamboo-hr.md).

# BambooHR

Connect BambooHR employee data, timesheets, and HR reports to Google Sheets, BigQuery, or your analytics tools via Coupler.io.

BambooHR is an HR management platform that centralizes employee data, time off tracking, timesheets, and workforce analytics. It's widely used by small and mid-sized businesses to manage their people operations in one place.

Connecting BambooHR to Coupler.io lets you pull your HR data into the tools and destinations you already use — without manual exports or CSV juggling.

**Why connect BambooHR to Coupler.io?**

* Sync employee directory data to spreadsheets or dashboards for headcount reporting
* Centralize time off requests and timesheet entries for payroll or workforce planning
* Combine HR data with data from other sources (e.g., project tools, finance systems) using Join or Append
* Send HR metrics to AI destinations like ChatGPT or Claude for summaries and workforce analysis

## Prerequisites

Before you connect, make sure you have:

* A BambooHR account with admin access (required to generate an API key)
* Your BambooHR **company subdomain** (the part before `.bamboohr.com` in your URL)
* An API key generated from your BambooHR account settings

To generate an API key in BambooHR: go to your profile icon → **API Keys** → **Add New Key**.

## Quick start

{% hint style="success" %}
Start with the **Employees directory** entity to get a full snapshot of your workforce — it's the most commonly used entity and a great foundation for headcount dashboards.
{% endhint %}

## How to connect

{% stepper %}
{% step %}
**Create a new data flow in Coupler.io.** From your Coupler.io dashboard, click **Add data flow** and search for **BambooHR** as your source.
{% endstep %}

{% step %}
**Enter your BambooHR credentials.** You'll be asked for your API key and your company subdomain. Paste both into the fields provided.
{% endstep %}

{% step %}
**Select an entity.** Choose what data you want to pull — for example, **Employees directory streams**, **Time off requests streams**, or **Timesheet entries**. You can add more entities to the same data flow later.
{% endstep %}

{% step %}
**Choose a destination.** Select where you want your data to land — Google Sheets, Excel, BigQuery, Looker Studio, or an AI destination like ChatGPT, Claude, or Gemini.
{% endstep %}

{% step %}
**Run the data flow.** Click **Run** to execute your first manual sync and confirm that data is flowing correctly.
{% endstep %}
{% endstepper %}

## BambooHR data overview

BambooHR exposes five entities through Coupler.io, covering employee records, time tracking, and configurable HR reports. Here's a breakdown of what each entity contains and how you can use the data.

## Entities

| Entity                      | Best used for                                               |
| --------------------------- | ----------------------------------------------------------- |
| Custom reports streams      | Pulling specific HR fields into tailored reports            |
| Employees directory streams | Headcount tracking, org charts, workforce snapshots         |
| Meta fields streams         | Discovering available fields before building custom reports |
| Time off requests streams   | Leave management, absence tracking, PTO analysis            |
| Timesheet entries           | Hours worked, attendance, payroll prep                      |

## Available data by entity

#### Employees directory streams

| Field                  | Description                         |
| ---------------------- | ----------------------------------- |
| Employee ID            | Unique identifier for each employee |
| First name / Last name | Employee's full name                |
| Job title              | Current role                        |
| Department             | Team or business unit               |
| Location               | Office or remote location           |
| Employment status      | Active, terminated, or on leave     |
| Hire date              | Date the employee joined            |
| Manager                | Reporting manager's name or ID      |

#### Time off requests streams

| Field                 | Description                        |
| --------------------- | ---------------------------------- |
| Request ID            | Unique ID for the time off request |
| Employee ID           | Who submitted the request          |
| Start date / End date | Duration of the time off period    |
| Type                  | Vacation, sick, personal, etc.     |
| Status                | Approved, pending, or denied       |
| Amount                | Hours or days requested            |
| Notes                 | Any comments added to the request  |

#### Timesheet entries

| Field                 | Description                                           |
| --------------------- | ----------------------------------------------------- |
| Employee ID           | Who the entry belongs to                              |
| Date                  | Day the hours were logged                             |
| Hours worked          | Total time recorded                                   |
| Start time / End time | Clock-in and clock-out times (if tracked)             |
| Project / Task        | Work item the hours are attributed to (if configured) |

#### Custom reports streams

This entity returns the fields you specify using BambooHR's field name list. You configure which fields to include by entering them as a comma-separated list (e.g., `firstName,lastName,department,salary`). Use the **Meta fields streams** entity first to discover available field names in your account.

#### Meta fields streams

| Field      | Description                        |
| ---------- | ---------------------------------- |
| Field ID   | Internal BambooHR field identifier |
| Field name | Human-readable name                |
| Type       | Data type (text, date, list, etc.) |
| Alias      | Short name used in API calls       |

## Common metric combinations

* **Headcount by department**: use Employees directory → group by Department
* **Absence rate**: combine Time off requests with Employees directory using a Join on Employee ID
* **Hours worked per team**: use Timesheet entries → group by Department (after joining with Employees directory)
* **PTO utilization**: compare Time off requests (approved) against employee tenure from hire date

## Use cases by role

{% tabs %}
{% tab title="HR teams" %}

* Build live headcount dashboards in Google Sheets or Looker Studio using the Employees directory entity
* Track PTO trends and approval rates from Time off requests data
* Use the Custom reports entity to pull compensation or performance fields for HR reviews
* Send workforce summaries to Claude or ChatGPT for narrative reporting
  {% endtab %}

{% tab title="Finance teams" %}

* Export Timesheet entries into Excel for payroll reconciliation
* Join Employees directory with Timesheet entries to calculate labor costs by department
* Aggregate headcount and time off data in BigQuery for workforce cost modeling
  {% endtab %}

{% tab title="Operations" %}

* Append data from multiple BambooHR accounts (e.g., different subsidiaries) using the Append transformation
* Monitor absence patterns using Time off requests filtered by date range
* Use Meta fields to audit which HR fields are populated across your employee base
  {% endtab %}
  {% endtabs %}

## Platform-specific notes

* The **start date** parameter applies only to Time off requests — it defaults to 30 days back if not set. Use the date picker to extend the range for historical analysis.
* Custom reports fields must match BambooHR's official field name aliases exactly. Use the Meta fields entity to look these up before configuring your custom report.
* The Employees directory typically reflects **active employees only** — terminated employees may not appear depending on your BambooHR account configuration.
* Timesheet data is only available if your BambooHR plan includes time tracking.

## BambooHR common issues

### Connection issues

<details>

<summary>Invalid API key error when connecting</summary>

Double-check that you've copied the full API key from BambooHR — it's easy to accidentally miss a character. Also confirm you're using the correct company subdomain (the part before `.bamboohr.com` in your BambooHR URL). The subdomain is case-sensitive.

To regenerate a key: go to your BambooHR profile → **API Keys** → **Add New Key**.

</details>

<details>

<summary>Connection succeeds but no data loads</summary>

This usually means the API key belongs to a user without sufficient permissions. BambooHR API access is tied to the user's role — make sure the key was generated by an **admin** or a user with access to the entities you're trying to pull.

</details>

### Missing data

<details>

<summary>Time off requests return no results</summary>

Check the **start date** parameter in your data flow settings. By default it looks back 30 days — if you're expecting older records, use the date picker to set an earlier start date. Also verify the request statuses you expect (approved, pending, denied) exist within that date range in BambooHR.

</details>

<details>

<summary>Timesheet entries are empty</summary>

Timesheet data is only available if your BambooHR subscription includes **time tracking**. If your plan doesn't include this feature, the entity will return no data. Check your BambooHR plan or contact BambooHR support to confirm.

</details>

<details>

<summary>Custom reports return no columns or fewer fields than expected</summary>

The `custom_reports_fields` parameter requires field aliases that exactly match BambooHR's field name list. A typo or unsupported field name will silently drop that column. Run the **Meta fields streams** entity first to get a list of valid field aliases for your account, then update your custom report fields accordingly.

</details>

<details>

<summary>Terminated employees are missing from the directory</summary>

The Employees directory entity typically returns active employees only. BambooHR's API behavior for terminated employees depends on your account configuration. If you need terminated employee records, check whether your BambooHR account is set to include them — or use a Custom report with a status field filter.

</details>

### Permission errors

<details>

<summary>403 Forbidden error on specific entities</summary>

{% hint style="warning" %}
Even if your API key is valid, BambooHR restricts access to certain data based on the generating user's role. A 403 on a specific entity means that user doesn't have permission to view that data type.
{% endhint %}

To fix this, regenerate the API key using a BambooHR admin account, or ask your BambooHR admin to grant the user access to the relevant data.

</details>

### Data discrepancies

<details>

<summary>Headcount in Coupler.io doesn't match BambooHR reports</summary>

BambooHR's built-in reports may apply filters (e.g., employment type, status) that aren't applied by default in the Employees directory API. Check whether the BambooHR report you're comparing against excludes contractors, part-time staff, or employees in specific statuses — and apply equivalent filters in your Coupler.io data flow or destination.

</details>

### Rate limits

<details>

<summary>Data flow fails with a rate limit error</summary>

BambooHR enforces API rate limits per account. If you're running multiple data flows against BambooHR simultaneously, they may compete for the same rate limit budget. Stagger your scheduled syncs to avoid hitting limits, and avoid running manual runs during scheduled sync windows.

</details>

## BambooHR FAQ

<details>

<summary>Where do I find my BambooHR API key?</summary>

Log in to BambooHR, click your profile icon in the top-right corner, and select **API Keys**. Click **Add New Key**, give it a name, and copy the generated key. You'll only see the full key once, so save it somewhere secure before closing the dialog.

</details>

<details>

<summary>What is my BambooHR subdomain?</summary>

Your subdomain is the company-specific part of your BambooHR URL. For example, if you access BambooHR at `acmecorp.bamboohr.com`, your subdomain is `acmecorp`. Enter just the subdomain — not the full URL.

</details>

<details>

<summary>Can I pull data from multiple BambooHR accounts into one report?</summary>

Yes. Add each BambooHR account as a separate source within the same data flow, then use the **Append** transformation to stack the data into a single table. This is useful for organizations with multiple subsidiaries or regional BambooHR instances.

</details>

<details>

<summary>How do I pull only specific employee fields instead of everything?</summary>

Use the **Custom reports streams** entity and enter the field aliases you want in the `custom_reports_fields` parameter as a comma-separated list (e.g., `firstName,lastName,department,jobTitle`). Run the **Meta fields streams** entity first to get a full list of valid aliases for your account.

</details>

<details>

<summary>Why does my time off data only go back 30 days?</summary>

The default start date for Time off requests is 30 days before today. To pull a longer history, go to your data flow settings and use the date picker in the **Start date** parameter to set an earlier date — for example, the beginning of the current year.

</details>

<details>

<summary>Can I use BambooHR data with AI tools like ChatGPT or Claude?</summary>

Yes. When setting up your data flow, select an AI destination — options include ChatGPT, Claude, Gemini, Perplexity, Cursor, and OpenClaw. This lets you send employee or HR data directly to an AI assistant for summaries, analysis, or Q\&A.

</details>

<details>

<summary>Why are timesheet entries empty even though I have data in BambooHR?</summary>

Timesheet entries are only available if your BambooHR subscription includes the time tracking add-on. If your plan doesn't include it, the entity will return no data. Check your BambooHR plan or contact BambooHR support to confirm whether time tracking is enabled.

</details>

<details>

<summary>Can I combine BambooHR data with data from other HR or finance tools?</summary>

Yes. Coupler.io supports multi-source data flows. You can join BambooHR employee data with, for example, payroll data from another source using the **Join** transformation on Employee ID — or combine HR metrics with finance data for workforce cost reporting.

</details>

{% hint style="info" %}
For field-level details on each entity, see the [Data Overview](#bamboohr-data-overview) article. For connection errors or missing data, check [Common Issues](#bamboohr-common-issues). For setup recommendations, visit [Best Practices](https://docs.coupler.io/sources/category/project-management/bamboo-hr/best-practices.md).
{% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.coupler.io/sources/category/project-management/bamboo-hr.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
