> ## Documentation Index
> Fetch the complete documentation index at: https://docs.serval.com/llms.txt
> Use this file to discover all available pages before exploring further.

# BambooHR

> BambooHR is an HR information system for employee records, time off, time tracking, and hiring - Serval connects to it with an API key so your workflows can read and update your HR data on demand.

## About BambooHR

BambooHR is a human resources information system (HRIS) for employee records, time off, time tracking, hiring, and HR reporting. Each Serval connection targets a single BambooHR company instance, identified by its API domain (for example, mycompany.bamboohr.com), using an API key you generate inside BambooHR. The connection acts as the BambooHR user who generated the key, so everything Serval can see or change is limited by that user's BambooHR permissions.

**Authentication:** API key, generated by a BambooHR user. There is no OAuth app to register - you paste the key and your API domain into Serval.

**Data sync:** On-demand only. There is no background or scheduled sync and Serval registers no BambooHR webhooks; data is read or changed only when a workflow runs.

## What the BambooHR integration enables

| Capability                                        | Description                                                                                                                                                   |
| ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Employee records                                  | Read the full employee directory, look up or update individual employees, and work with job and compensation history, photos, dependents, and employee files. |
| Time off                                          | Work with time-off policies and types, balances and balance adjustments, requests and approvals, history, and who's out.                                      |
| Time tracking and scheduling                      | Clock in/out, hour and timesheet entries, projects and tasks, break policies, schedules, and shifts.                                                          |
| Hiring and onboarding                             | Applicant tracking (applications, jobs, statuses, comments, hiring leads), new-hire packets, and onboarding experiences.                                      |
| Performance, compensation, benefits, and training | Employee goals, compensation planning cycles, pay grades and bands, total rewards, benefits, and training records.                                            |
| Reports, datasets, and metadata                   | Run custom reports, query datasets, and read account metadata such as fields, tables, lists, users, and company info.                                         |
| Full API access                                   | Workflows reach BambooHR through one generic action that covers the entire BambooHR REST API, so anything not listed above is still reachable.                |

Anything defined in the [BambooHR API](https://documentation.bamboohr.com/reference/getting-started) can be accessed through Serval.

## Get your credentials

You need a BambooHR API key. Keys are generated per user and inherit exactly that user's BambooHR permission level, so generate the key from an account whose access matches what your workflows need. BambooHR's own guide is here: [BambooHR API getting started](https://documentation.bamboohr.com/docs/getting-started).

<Steps>
  <Step title="Log in to BambooHR">
    Sign in to your BambooHR account.
  </Step>

  <Step title="Open your user menu">
    Click your name in the lower-left corner of any page.
  </Step>

  <Step title="Select API Keys">
    Choose **API Keys** from the menu. If you do not see it, your account lacks permission to create keys - contact your BambooHR administrator.
  </Step>

  <Step title="Add a new key">
    Click **Add New Key** and give it a descriptive name, such as "Serval Integration".
  </Step>

  <Step title="Generate and copy the key">
    Click **Generate Key**, then copy the key and store it securely.
  </Step>
</Steps>

<Warning>
  Anyone with this key can act as your BambooHR user. Treat it like a password and store it somewhere safe - you will paste it into Serval in the next section.
</Warning>

<Tip>
  Workflows will only ever see and change what the key's owner can see and change in BambooHR. If your workflows need broad employee data, generate the key from an account with the appropriate permission level.
</Tip>

## Connect in Serval

<Steps>
  <Step title="Open the BambooHR connect form in Serval">
    Start connecting BambooHR from Serval's integrations page.
  </Step>

  <Step title="Enter your API Domain (required)">
    Enter your full BambooHR domain, for example mycompany.bamboohr.com. Use the bare domain only - no "https\://", no path, and no trailing slash. Invalid values are rejected with the error "Must be a valid BambooHR domain (e.g., mycompany.bamboohr.com)".
  </Step>

  <Step title="Enter your API Key (required)">
    Paste the key you generated in BambooHR. The field's helper text reads: "Your BambooHR API key. Generate one by clicking your name in the lower left corner > API Keys".
  </Step>

  <Step title="Save the connection">
    Save the form to create the connection. Serval verifies it with a health check (see below).
  </Step>
</Steps>

<Note>
  If you edit this connection later - for example, to rotate your BambooHR API key - always re-enter the complete key in the **API Key** field before saving.
</Note>

## Verifying the connection

Serval verifies the connection with a single lightweight, read-only call to BambooHR (it reads your account's field metadata) using your saved API Domain and key. If that call succeeds, the connection is healthy. If it fails, the connection is marked unhealthy - a failure points to an authentication or domain problem (a bad or revoked API key, or a wrong API Domain) rather than a data issue.

<Tip>
  A healthy connection only proves the key and domain work. If a workflow gets permission errors or cannot see certain fields even though the connection is green, check the BambooHR permission level of the user who generated the key - that user's access is the ceiling for everything Serval can do.
</Tip>

## Gotchas and troubleshooting

<AccordionGroup>
  <Accordion title="Missing fields or permission errors usually mean the key's owner lacks access">
    BambooHR treats every request as if the user who generated the key were using the product. Field visibility and write access follow that user's BambooHR permission level, so missing fields or "permission denied" failures often mean the key's owner lacks access - not that the integration is broken. Fix it by adjusting that user's permissions in BambooHR or generating a key from a more privileged account.
  </Accordion>

  <Accordion title="API Domain must be the bare domain">
    The connect form only accepts a value shaped like mycompany.bamboohr.com - one subdomain followed by .bamboohr.com. Values with "https\://", a path, a trailing slash, or a non-bamboohr.com host are rejected with the error "Must be a valid BambooHR domain (e.g., mycompany.bamboohr.com)".
  </Accordion>

  <Accordion title="Employee fields vary per organization">
    BambooHR fields can be customized per company, so a field present in one organization's data may be absent in another's - and BambooHR only returns fields the key's user is allowed to see. Also note the employee directory returns all employees in one response, with no pagination.
  </Accordion>

  <Accordion title="Credentials are only ever sent to bamboohr.com addresses">
    Serval attaches your API key only to requests going to subdomains of bamboohr.com, and workflow calls are made against your configured API Domain. Requests to any other host are blocked from carrying the credential.
  </Accordion>
</AccordionGroup>

***

Need help? Contact **[support@serval.com](mailto:support@serval.com)** for assistance with your BambooHR integration.