Docs

Integrations / HR systems

BambooHR

Connect BambooHR to Risotto with OAuth, then use the BambooHR runbook templates for time off and home address requests

Connect BambooHR as your HRIS to power employee self-service. Once BambooHR is connected:

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 (for example, "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.

  1. Open the Connect BambooHR dialog

    Go to Settings > Integrations and click BambooHR, in the HRIS category. On the API access card, click Connect.

  2. Enter your company subdomain

    In the Connect BambooHR dialog, enter your Company Subdomain, the acme part of acme.bamboohr.com, and click Continue.

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

  4. Confirm the connection

    Risotto opens the BambooHR integration page. A toast confirms "BambooHR connected successfully", and the API access card shows Connected. If the install fails, the toast starts with "BambooHR connection failed".

Requested OAuth scopes

During install, Risotto requests the following BambooHR OAuth scopes:

ScopePurpose
offline_accessIssue refresh tokens so Risotto keeps access without re-prompting your admin
openid, emailIdentify the BambooHR account that approved the install
employeeRead basic employee records
employee:nameRead first, last, display, and preferred name
employee:contactRead work and home email
employee:jobRead job title, department, division, location, hire date, and supervisor
employee:managementRead manager / supervisor relationships
sensitive_employee:addressRead the employee's home address
sensitive_employee:address.writeUpdate the employee's home address
time_offRead PTO policy types, balances, and existing time off requests
time_off.writeSubmit 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. Risotto writes to BambooHR only when a runbook uses the Request BambooHR Time Off or Update BambooHR Home Address tool.

Employee profile (read)

Pulled from GET /api/v1/employees/{id}:

BambooHR fieldUsed for
firstName, lastNameName resolution and personalization
displayNamePreferred display name in Risotto responses
preferredNameFallback display name when displayName is empty
workEmailPrimary identifier matched against the requester's Slack email
homeEmailSecondary identifier when workEmail is missing
jobTitleEmployee profile lookups
departmentEmployee profile lookups
divisionEmployee profile lookups
locationWork location lookups
hireDateStart date lookups
supervisor"Who's my manager?" style lookups
supervisorEmailRouting requests that need manager approval
employmentHistoryStatusDetecting 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} by the Update BambooHR Home Address tool:

BambooHR fieldUsed for
address1Street address line 1
address2Street address line 2
cityCity
stateState or province
countryCountry
zipcodePostal / ZIP code

Time off (read and write)

BambooHR endpointUsed for
GET /api/v1/employees/{id}/time_off/calculatorCurrent 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
PUT /api/v1/employees/{id}/time_off/requestSubmit a new time off request. Requests are created with status requested and routed for approval

Set up time off and home address requests

Time off and home address requests use the BambooHR runbook templates in Runbooks > Templates. Each template needs BambooHR tools, which you create from the template's page.

TemplateWhat the agent doesTools it needs
BambooHR Time Off RequestLooks up the requester's balances and submits time off requests in BambooHR. Changes to booked time off go to HR.Get BambooHR Time Off Balance, Request BambooHR Time Off
BambooHR Time Off BalanceLooks up the requester's balances. Escalates every request to take, change, or cancel time off to HR.Get BambooHR Time Off Balance
BambooHR Home Address UpdateLooks up the requester's home address, confirms the new address with them, and saves it in BambooHR.Get BambooHR Home Address, Update BambooHR Home Address
BambooHR Home Address LookupLooks up the requester's home address. Collects a new address and escalates the change to HR.Get BambooHR Home Address

Each pair matches the same requests, so turn on only one template of each pair. The other BambooHR template is BambooHR Support, which gives guidance from your knowledge base and BambooHR's documentation. If it is on, it also matches some time off and address requests. Remove those terms from its conditions, or turn it off.

  1. Find the BambooHR templates

    Go to Runbooks and click Browse templates. Type BambooHR in Search templates. The HR group lists the time off and home address templates.

  2. Open a template

    Click the template, for example BambooHR Time Off Request. The page shows the template's match condition, its agent instructions, the Required tools, and Tips in the side panel.

  3. Create the required tools

    Under Required tools, click Create beside each tool that shows Not set up. The tool editor opens for that tool. Keep Restrict to Requestor Only on, so the tool works only on the requester's own record. To have a person review each time off request or address change before it reaches BambooHR, turn on Requires Approval on the request or update tool. Save the tool, and the dashboard returns to the template. If a tool shows Disabled, click Enable.

  4. Use the template

    Click Use this template. The button is available once every required tool is ready. If your organization has more than one tool for a required tool, the Choose tool instances dialog asks which one to use: pick one for each and click Continue. The runbook editor opens with the template filled in. Save the runbook and turn it on, as in Create a runbook.

The templates act only for the requester. Before the agent submits time off or changes an address, it confirms the details with the requester and waits for their reply. For a time off type counted in days, the agent requests 1 for each full day, or a part such as 0.5 for a half day. For a type counted in hours, it asks how many hours.

Runbook tools

You can also add BambooHR tools to your own runbooks. Create them on the Tools page:

ToolWhat it does
Get BambooHR Employee InfoReads the employee's profile from BambooHR
Get BambooHR Time Off BalanceReads the employee's balances and the time off types they can request
Request BambooHR Time OffSubmits a time off request with status requested
Get BambooHR Home AddressReads the employee's home address
Update BambooHR Home AddressChanges the employee's home address in BambooHR
  • Each tool has a Restrict to Requestor Only option, which is on by default. When it is on, the tool works only for the requester of the ticket.
  • Request BambooHR Time Off needs the employee's confirmation, given after the agent asks for it. It does not submit a request for a time off type the employee cannot use, for dates that already have time off, or for more time than the balance allows. Requests follow your BambooHR approval flow.

Terminated employees

When the BambooHR webhook reports that an employee's status changed to Terminated, or that the employee was deleted, Risotto marks the employee inactive and stops looking up their BambooHR record. The BambooHR tools and the employee record lookup then find no record for them. This needs the webhook. A status change back from Terminated makes the employee active again.

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

  1. Open the webhook dialog

    On the BambooHR integration page (Settings > Integrations > BambooHR), click Connected on the API access card, then click Configure webhook.... Click the copy button beside the Webhook URL in the Configure BambooHR webhook dialog.

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

  3. 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. The key is write-only. To replace it, paste a new key and click Save. To remove it, click Remove key.

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:

TriggerBambooHR sends it when
Employee createdHR adds the employee in BambooHR. It comes once, when the record is saved, not on the hire date.
Employment status changedThe employee's employment status changes, including to Terminated or to a custom status.
Employee terminatedThe 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

FieldWhat it holds
employee_emailThe employee's BambooHR workEmail, empty when it is not a valid email address
employee_nameTheir display name, or their first and last name
hris_employee_idTheir BambooHR employee ID
event_timeWhen Risotto received the event
start_dateEmployee created only: the employee's hire date
employment_statusEmployment status changed only: the new status
effective_dateEmployment status changed only: the date the new status takes effect
end_dateEmployee 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 API access card of the BambooHR integration page, then click Disconnect.... In the Disconnect from BambooHR? dialog, click Disconnect. Risotto deletes 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.

Something wrong or missing? Report an issue · View as Markdown