BambooHR - Risotto

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 settings. In the dashboard, BambooHR appears as a row under Settings > People > Connect with the description “Allows Risotto to manage HR operations like employee data and time off” and a Connect button on the right.

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.

Start the install from Risotto

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.

Approve the install in BambooHR

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.

Confirm the connection

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:

Get Employee Info

Look up the requesting employee’s profile, title, department, work location, manager, and start date. Turn it on in Support agent > Context.

Get Home Address

View the home address on file for the requesting employee.

Update Home Address

Update the home address on file for the requesting employee.

Get PTO Balance

Retrieve balances for each policy type the employee is assigned to.

Request PTO

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 stop running for that employee and requests are escalated, even if their Slack account is still active.

Automation triggers

BambooHR employee events can start a Risotto automation. The events come from a BambooHR webhook, so an admin must configure the webhook first.

Configure the webhook

Open the webhook dialog

In Settings > People > Connect, click Connected on the BambooHR row, then click Configure webhook…. Copy the Webhook URL from the Configure BambooHR webhook dialog.

Create the webhook in BambooHR

In BambooHR, go to Settings > Account > Webhooks and create a webhook with the URL. Subscribe to the Employee Created, Employee Updated, and Employee Deleted events, and to the fields Employment Status, Employment status comments, and Employment status: Date. In the Data section, select JSON for the data format.

Save the signature key in Risotto

Copy the private signature key of the webhook from BambooHR. Paste it in the Private Signature Key field of the dialog, then click Save. Risotto uses the key to check that each event comes from BambooHR.

Until the connection works and the key is saved, the trigger picker shows the BambooHR events as unavailable, with “BambooHR is not connected, needs to be reauthorized, or its webhook is not configured.” Only events that BambooHR sends after you configure the webhook start runs.

Triggers

In the trigger picker, open BambooHR and choose an event:

Trigger	BambooHR sends it when
Employee created	HR adds the employee in BambooHR. It comes once, when the record is saved, not on the hire date.
Employment status changed	The employee’s employment status changes, including to Terminated or to a custom status.
Employee terminated	The employee’s employment status changes to BambooHR’s built-in Terminated status.

A custom status such as “Resigned” starts only Employment status changed. A change to Terminated starts both status triggers.
A rehire uses the existing record in BambooHR, so it does not send Employee created again.
HR often adds the work email after the record is created. Then Employee created runs with an empty employee_email.
A status change with an effective date in the future may not send an event on that date.
When BambooHR deletes an employee, Risotto marks the employee inactive. No automation runs.

What the automation receives

Field	What it holds
`employee_email`	The employee’s BambooHR `workEmail`, empty when it is not a valid email address
`employee_name`	Their display name, or their first and last name
`hris_employee_id`	Their BambooHR employee ID
`event_time`	When Risotto received the event
`start_date`	Employee created only: the employee’s hire date
`employment_status`	Employment status changed only: the new status
`effective_date`	Employment status changed only: the date the new status takes effect
`end_date`	Employee terminated only: the date the Terminated status takes effect

When BambooHR has no date on file, the date Risotto received the event stands in for it. An automation runs once for each event, even if BambooHR sends it more than once.

Disconnecting

To disconnect Risotto from BambooHR, click Connected on the BambooHR row in People Connect, then click Disconnect… and confirm. 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.

Settings

​How the Integration Works

​Install from BambooHR

​Requested OAuth Scopes

​Data Fields That Sync

​Employee profile (read)

​Home address (read and write)

​Time off (read and write)

​Supported Actions

Get Employee Info

Get Home Address

Update Home Address

Get PTO Balance

Request PTO

​Terminated Employees

​Automation triggers

​Configure the webhook

​Triggers

​What the automation receives

​Disconnecting

How the Integration Works

Install from BambooHR

Requested OAuth Scopes

Data Fields That Sync

Employee profile (read)

Home address (read and write)

Time off (read and write)

Supported Actions

Terminated Employees

Automation triggers

Configure the webhook

Triggers

What the automation receives

Disconnecting