# BambooHR

BambooHR is a cloud-based HR platform for small and medium businesses. The Sling BambooHR connector extracts data from the BambooHR REST API, supporting employee directory, job history, compensation, time off, time tracking, training, goals, and applicant tracking data.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `api_key` **(required)** -> Your BambooHR API key

**Inputs:**

* `company_domain` **(required)** -> Your BambooHR company subdomain (e.g. `mycompany` from `mycompany.bamboohr.com`)
* `anchor_date` (optional) -> Starting date for incremental sync (default: 1 year ago). Format: `YYYY-MM-DD`

### Authentication

BambooHR uses **API Key** authentication (HTTP Basic Auth with the API key as username):

1. Log in to your BambooHR account
2. Click your profile picture in the upper right corner
3. Select **API Keys**
4. Click **Add New Key**, give it a name, and click **Generate Key**
5. Copy the API key (it will only be shown once)

{% hint style="info" %}
**Permissions:** The API key inherits the permissions of the user who created it. Ensure the user has access to the data you want to extract.
{% endhint %}

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set BAMBOOHR type=api spec=bamboohr secrets='{ api_key: your_api_key }' inputs='{ company_domain: mycompany }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export BAMBOOHR='{ type: api, spec: bamboohr, secrets: { api_key: "your_api_key" }, inputs: { company_domain: "mycompany" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  BAMBOOHR:
    type: api
    spec: bamboohr
    secrets:
      api_key: "your_api_key"
    inputs:
      company_domain: "mycompany"
```

**With anchor date for historical data:**

```yaml
connections:
  BAMBOOHR:
    type: api
    spec: bamboohr
    secrets:
      api_key: "your_api_key"
    inputs:
      company_domain: "mycompany"
      anchor_date: "2023-01-01"
```

## Replication

Here's an example replication configuration to sync BambooHR data to a PostgreSQL database:

```yaml
source: BAMBOOHR
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: bamboohr.{stream_name}

streams:
  # Employee directory (populates queue for per-employee endpoints)
  employees:

  # Metadata
  meta_fields:
  meta_tables:
  meta_users:
  meta_lists:

  # Time off
  time_off_types:
  time_off_policies:
  time_off_requests:
    mode: incremental
  whos_out:

  # Time tracking
  timesheet_entries:
    mode: incremental

  # Per-employee tables
  job_info:
  employment_status:
  compensation:

  # Training
  training_categories:
  training_types:
  training:

  # Goals
  goals:

  # Applicant tracking
  job_summaries:
  job_applications:
    mode: incremental
```

## Endpoints

### Employee Directory

| Endpoint    | Description                         | Incremental |
| ----------- | ----------------------------------- | ----------- |
| `employees` | Employee directory with core fields | No          |

### Metadata

| Endpoint      | Description                                     | Incremental |
| ------------- | ----------------------------------------------- | ----------- |
| `meta_fields` | Available employee fields in the account        | No          |
| `meta_tables` | Available tabular fields and table metadata     | No          |
| `meta_users`  | All active BambooHR user accounts               | No          |
| `meta_lists`  | Details for list-type fields (dropdown options) | No          |

### Time Off

| Endpoint            | Description                                  | Incremental |
| ------------------- | -------------------------------------------- | ----------- |
| `time_off_types`    | Time off types (Vacation, Sick, etc.)        | No          |
| `time_off_policies` | Time off policies                            | No          |
| `time_off_requests` | Time off requests                            | Yes         |
| `whos_out`          | Employees currently out or on upcoming leave | No          |

### Time Tracking

| Endpoint            | Description       | Incremental |
| ------------------- | ----------------- | ----------- |
| `timesheet_entries` | Timesheet entries | Yes         |

### Employee Tables (Per-Employee)

| Endpoint            | Description                                        | Incremental |
| ------------------- | -------------------------------------------------- | ----------- |
| `job_info`          | Employee job history (title, department, location) | No          |
| `employment_status` | Employment status history (active, terminated)     | No          |
| `compensation`      | Compensation history (pay rate, type, schedule)    | No          |

### Training

| Endpoint              | Description                                    | Incremental |
| --------------------- | ---------------------------------------------- | ----------- |
| `training_categories` | Training categories                            | No          |
| `training_types`      | Training types with requirements and frequency | No          |
| `training`            | Employee training records (per-employee)       | No          |

### Goals

| Endpoint | Description                                | Incremental |
| -------- | ------------------------------------------ | ----------- |
| `goals`  | Employee goals and progress (per-employee) | No          |

### Applicant Tracking

| Endpoint           | Description              | Incremental |
| ------------------ | ------------------------ | ----------- |
| `job_summaries`    | ATS job postings summary | No          |
| `job_applications` | Job applications         | Yes         |

To discover available endpoints:

```bash
sling conns discover BAMBOOHR
```

## Parent-Child Endpoints

The `employees` endpoint populates an `employee_ids` queue, which feeds the following per-employee endpoints:

* `job_info` — job history per employee
* `employment_status` — status history per employee
* `compensation` — compensation history per employee
* `training` — training records per employee
* `goals` — goals per employee

Ensure the `employees` endpoint runs before these child endpoints in your replication configuration.

## Incremental Sync

The BambooHR connector supports date-range-based incremental sync for:

* **`time_off_requests`** — syncs by start date
* **`timesheet_entries`** — syncs by start date
* **`job_applications`** — syncs by applied date (via `newSince` parameter)

**First run:** Fetches records from `anchor_date` (default: 1 year ago) to present. **Subsequent runs:** Only fetches records after the last sync checkpoint.

## Rate Limiting

The connector handles BambooHR's rate limits automatically:

* Uses conservative rate limiting (3 requests/second, 2 concurrent)
* Retries with exponential backoff on 429 and 503 responses
* Maximum 5 retry attempts

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).