# 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.