Skip to main content

​
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

Anything defined in the BambooHR API can be accessed through Serval.

​
Installable workflows

Each workflow identifies the requesting employee automatically, so people can act on their own data without looking up IDs. Read-only workflows run without approval by default. Workflows that write back to BambooHR - Request Time Off in BambooHR and Update My BambooHR Contact Info - require approval by the installer by default. All writes are still bounded by the API key owner’s BambooHR permissions.

​
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.
1

Log in to BambooHR

Sign in to your BambooHR account.
2

Open your user menu

Click your name in the lower-left corner of any page.
3

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

Add a new key

Click Add New Key and give it a descriptive name, such as “Serval Integration”.
5

Generate and copy the key

Click Generate Key, then copy the key and store it securely.
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.
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.

​
Connect in Serval

1

Open the BambooHR connect form in Serval

Start connecting BambooHR from Serval’s integrations page.
2

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

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”.
4

Save the connection

Save the form to create the connection. Serval verifies it with a health check (see below).
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.

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

​
Gotchas and troubleshooting

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.
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)”.
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.
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.
Need help? Contact support@serval.com for assistance with your BambooHR integration.