> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tryrisotto.com/llms.txt
> Use this file to discover all available pages before exploring further.
# BambooHR
> Connect BambooHR as your HRIS to power employee self-service
Connect BambooHR as your HRIS so Risotto can answer employee questions and take actions like checking PTO balances, submitting time off requests, and updating home addresses. These actions are all controlled by the [People Actions](/dashboard/settings/people/actions) settings.
## How the Integration Works
Risotto connects to BambooHR through BambooHR's OAuth 2.0 authorization flow. Each Risotto org installs against a single BambooHR tenant identified by your **company subdomain** (the `acme` in `acme.bamboohr.com`). After install, Risotto stores access and refresh tokens scoped to that tenant and uses them to call the BambooHR REST API on your behalf.
When an employee asks Risotto something that needs HRIS data (i.e. "What's my PTO balance?"), Risotto resolves their BambooHR employee record by matching their work email, then calls only the BambooHR endpoints required to answer that request.
## Install from BambooHR
You must be a BambooHR admin to approve the install.
In the dashboard, go to **Settings > People > Connect** and click **Connect** next to BambooHR. Enter your BambooHR company subdomain (`acme` portion of `acme.bamboohr.com`) and click **Continue**.
You'll be redirected to your BambooHR tenant (`acme.bamboohr.com`) to
sign in and approve the requested OAuth scopes for the Risotto app. BambooHR
redirects you back to the Risotto dashboard once the install is complete.
The BambooHR row in **People Connect** updates to show the integration is connected.
The subdomain accepts lowercase letters, numbers, and hyphens only. If you're
unsure of your subdomain, check the URL you use to sign in to BambooHR.
A BambooHR tenant can only be connected to one Risotto org at a time. If the
same subdomain is already connected to another Risotto org, the install fails
with "Please disconnect BambooHR from your other Risotto org." Disconnect from
the other org first, then retry the install.
## Requested OAuth Scopes
During install, Risotto requests the following BambooHR OAuth scopes:
| Scope | Purpose |
| ---------------------------------- | ---------------------------------------------------------------------------- |
| `offline_access` | Issue refresh tokens so Risotto keeps access without re-prompting your admin |
| `openid`, `email` | Identify the BambooHR account that approved the install |
| `employee` | Read basic employee records |
| `employee:name` | Read first, last, display, and preferred name |
| `employee:contact` | Read work and home email |
| `employee:job` | Read job title, department, division, location, hire date, and supervisor |
| `employee:management` | Read manager / supervisor relationships |
| `sensitive_employee:address` | Read the employee's home address |
| `sensitive_employee:address.write` | Update the employee's home address |
| `time_off` | Read PTO policy types, balances, and existing time off requests |
| `time_off.write` | Submit time off requests on behalf of the requesting employee |
## Data Fields That Sync
Risotto reads only the fields it needs to fulfill an active request. Nothing is written back to BambooHR unless the matching People Action is enabled.
### Employee profile (read)
Pulled from `GET /api/v1/employees/{id}`:
| BambooHR field | Used for |
| ------------------------- | -------------------------------------------------------------- |
| `firstName`, `lastName` | Name resolution and personalization |
| `displayName` | Preferred display name in Risotto responses |
| `preferredName` | Fallback display name when `displayName` is empty |
| `workEmail` | Primary identifier matched against the requester's Slack email |
| `homeEmail` | Secondary identifier when `workEmail` is missing |
| `jobTitle` | Employee profile lookups |
| `department` | Employee profile lookups |
| `division` | Employee profile lookups |
| `location` | Work location lookups |
| `hireDate` | Start date lookups |
| `supervisor` | "Who's my manager?" style lookups |
| `supervisorEmail` | Routing requests that need manager approval |
| `employmentHistoryStatus` | Detecting whether the employee is currently active |
### Home address (read and write)
Pulled from `GET /api/v1/employees/{id}` when address access is needed, and written back via `POST /api/v1/employees/{id}` when **Update Home Address** is enabled:
| BambooHR field | Used for |
| -------------- | --------------------- |
| `address1` | Street address line 1 |
| `address2` | Street address line 2 |
| `city` | City |
| `state` | State or province |
| `country` | Country |
| `zipcode` | Postal / ZIP code |
### Time off (read and write)
| BambooHR endpoint | Used for |
| ---------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `GET /api/v1/employees/{id}/time_off/calculator` | Current balance, units (hours or days), and policy type for each plan the employee is assigned to |
| `GET /api/v1/time_off/requests` (filtered by `employeeId`) | Recent and upcoming time off requests for the employee |
| `POST /api/v1/employees/{id}/time_off/request` | Submit a new time off request. Requests are created with status `requested` and routed for approval |
Discretionary and manual BambooHR policies don't track a running balance, so
Risotto surfaces those as "no tracked balance" rather than a literal `0`.
## Supported Actions
BambooHR supports the following [People Actions](/dashboard/settings/people/actions):
Look up the requesting employee's profile, title, department, work location,
manager, and start date.
View the home address on file for the requesting employee.
Update the home address on file for the requesting employee.
Retrieve balances for each policy type the employee is assigned to.
Submit a time off request for the requesting employee. Requests are created
with status `requested` and follow your BambooHR approval flow.
## Terminated Employees
Risotto checks the `employmentHistoryStatus` field on every BambooHR lookup. When the field indicates the employee is no longer active, [People Actions](/dashboard/settings/people/actions) stop running for that employee and requests are escalated, even if their Slack account is still active.
## Disconnecting
To disconnect Risotto from BambooHR, click **Disconnect** on the BambooHR row in **People Connect**. Risotto revokes its stored access and refresh tokens. To fully remove the app from BambooHR, an admin should also revoke the Risotto authorization from **Account > API Keys & Installed Apps** inside BambooHR.