> For the complete documentation index, see [llms.txt](https://support.suptask.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://support.suptask.com/integrations-automations-and-workflows/integration-guides/bamboohr.md).

# BambooHR

Connect and manage employee data from Suptask workflows

{% hint style="warning" %}
This integration is a part of AI workflows in the Custom Enterprise plan. Additional cost might apply.
{% endhint %}

The BambooHR connector links Suptask to your BambooHR account. Once connected, a Suptask AI Assistant can look up employees, see who's out, and read time off requests and balances - and, depending on the permissions you grant, create or update employees and manage time off requests directly from a ticket.

To connect it, you generate an **API key** in BambooHR and paste it into Suptask together with your **company domain**. What the connector can reach is decided by the access level of the BambooHR user who generated the key.

**Use cases:**

* Answer "how many vacation days do I have left?" without an agent looking it up.
* Enrich an HR or IT ticket with the requester's department, manager or start date.
* See who is out today or this week before assigning a ticket.
* Onboard a new hire by creating their employee record from the ticket.
* Update an employee record as part of a change request.
* Submit or handle a time off request on behalf of a requester.

***

### Before you begin

You'll need:

* An **admin** role in Suptask.
* An **admin** role in BambooHR, or the rights to create access levels and users.
* The **Inbox** and **Assistant** you want to connect BambooHR to.

What you'll do:

* Create a custom access level in BambooHR for Suptask
* Add a dedicated user to that access level
* Generate an API key as that user
* Paste the API key and company domain into Suptask
* Enable the tools your Assistant should use

{% hint style="warning" %}
A BambooHR API key inherits the permissions of the user who generated it. A key generated by a full admin gives Suptask full admin access. Create a dedicated user with its own access level instead, so you stay in control of what the connector can reach.
{% endhint %}

{% hint style="info" %}
Keep the Connect BambooHR window in Suptask open in a separate browser tab. You'll switch back to it at the end.
{% endhint %}

***

### Step 1: Create a custom access level in BambooHR

The access level defines what Suptask can see and change. Creating a dedicated one keeps the access easy to review, and easy to widen or narrow later without affecting anyone else.

1. In BambooHR, click the **gear icon** in the top-right corner to open **Settings**.
2. Open **Access Levels**.
3. Click **+** and choose **Custom Access Level**.
4. Give it a name, for example `Suptask AI Integration`, and a description.
5. Continue to the permission steps and set what the level can do and see (see the table below).
6. Save the access level.

BambooHR splits permissions into **what this access level can do** and **what this access level can see**. Read tools need **View only** on the relevant fields and categories. Write tools need **Edit**.

| The Assistant should                                   | Grant in BambooHR                                                                            |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------- |
| Look up employees and read their details               | **View only** on the employee fields you want available, under **See about other employees** |
| See who's out, and read time off balances and requests | **View only** on the time off categories you want available                                  |
| Create or update employees                             | **Edit** on the employee fields that should be writable, plus permission to add employees    |
| Submit or manage time off requests                     | **Edit** on time off requests                                                                |

{% hint style="info" %}
Set the scope at the top of the What this Access Level Can See screen to All Employees if the Assistant should be able to answer for anyone in the company. Narrow it if the connector should only reach part of the organization.
{% endhint %}

{% hint style="warning" %}
The access level is the outer boundary. Suptask can never read or change more than the user is allowed to - so if a tool returns nothing, the access level is the first place to look.
{% endhint %}

***

### Step 2: Add a dedicated user to the access level

This user exists only for the integration. Using a dedicated user instead of a personal account means the connector keeps working even if the person who set it up leaves the company.

1. In **Settings → Access Levels**, select the access level you just created.
2. Open the small **gear icon** and choose **Add a Non-Employee BambooHR User**.
3. Enter a name, for example `Suptask AI`, and an email address you can access.
4. Make sure the access level is set to the one you created.
5. Save. BambooHR sends an invitation email to that address.
6. Open the email and set a password for the user.

***

### Step 3 - Generate the API key

1. Log in to BambooHR as the dedicated user you just created.
2. Click your **name or profile icon** in the lower-left corner to open the user menu.
3. Select **API Keys**.
4. Click **Add New Key**, give it a name such as `Suptask`, and generate it.
5. Copy the key.

{% hint style="warning" %}
BambooHR shows the full API key only when you create it. Copy it and store it securely before you leave the page - if you lose it, generate a new key.
{% endhint %}

{% hint style="info" %}
If API Keys or Add New Key isn't available, the user's access level doesn't allow API keys. Adjust the access level in Settings → Access Levels and try again.
{% endhint %}

***

### Step 4 - Connect BambooHR in Suptask

1. In Suptask, go to **Intelligence** in the menu and select the **Inbox**.
2. Add the **BambooHR** connector.
3. Paste your **API Key**.
4. Enter your **Company domain**. This is the part of your BambooHR URL that comes before `.bamboohr.com` - for `acme.bamboohr.com` the company domain is `acme`.
5. Click **Connect**.

When it's done, the connector status changes to **Connected**.

***

### Choose how each tool runs

Each tool is set to **Off**, **Ask** or **Auto**. This is where you decide how much the Assistant handles on its own.

* **Off** - the Assistant can't use the tool at all.
* **Ask** - the Assistant pauses and asks an agent to approve before the tool runs.
* **Auto** - the Assistant runs the tool on its own when it needs it.

A good starting point:

* Set the **read** tools to **Auto** so the Assistant can answer questions and enrich tickets without slowing anyone down.
* Set the **write** tools - Create Employee, Update Employee, Submit Time Off Request and Update Time Off Request - to **Ask** so an agent approves every change before it reaches BambooHR.
* Set anything your team doesn't need to **Off**.

{% hint style="info" %}
Tools are set per Assistant, so two Assistants on the same Inbox can use the same connector differently. An HR Assistant might create and update employees, while a general IT Assistant only reads employee details.
{% endhint %}

***

### Example workflows

{% hint style="info" %} Every Assistant can be customized to your needs. Below are examples of how the BambooHR connector can work once connected. {% endhint %}

**A) Answer a time off question automatically**

1. A user submits a ticket asking how much vacation they have left.
2. The Assistant looks up the requester in BambooHR and reads their time off balance.
3. The answer is posted on the ticket - either directly to the requester, or only visible to agents.

**B) Enrich a ticket for the agent**

1. A ticket arrives in the IT Inbox.
2. The Assistant reads the requester's department, manager and location from BambooHR.
3. The details are posted on the ticket, so the agent knows who they're helping without opening BambooHR.

**C) Onboard a new hire with approval**

1. An HR ticket requests onboarding for a new employee.
2. The Assistant collects the details it needs from the ticket.
3. Because **Create Employee** is set to **Ask**, the Assistant pauses and presents the change.
4. An agent approves, and the employee record is created in BambooHR.

***

### Create tickets from BambooHR events

You can also let BambooHR start the work in Suptask, without using the connector at all.

Suptask reads messages posted by other Slack apps and can create a ticket from each one. So when BambooHR posts into a Slack channel - a new hire starting, a role change, an approaching last day - Suptask picks the message up and turns it into a ticket for the right team.

**How to set it up**

1. Create a **dedicated Slack channel** for the integration, for example `#bamboohr-events`.
2. In Suptask, configure a **Form** in your Inbox with the Form type **Auto Creation of Tickets in Slack Channels**, and select that channel.
3. In BambooHR, set up the alert or workflow that should post a message to the channel.
4. Suptask creates a ticket from each new message, with the message content as the ticket description.

{% hint style="info" %}
Only one Form can be configured per channel. If you want different BambooHR events routed to different Inboxes, have BambooHR post to a separate channel per event type and configure one Form per channel.
{% endhint %}

Read more about how ticket creation from other Slack apps works:

{% content-ref url="/pages/xzp2WBZUGYEW9MpKuI5c" %}
[Integrate any app that posts in Slack](/integrations-automations-and-workflows/integration-guides/how-to-automate-and-integrate-suptask-with-other-slack-apps.md)
{% endcontent-ref %}

**Combine both directions**

The two work well together. BambooHR announces a new hire in Slack, Suptask creates the onboarding ticket, and the Assistant on that Inbox uses the BambooHR connector to read the employee's details and complete the remaining steps - all on the same ticket.

***

### How to use the integration

This connector is used by the AI Assistants you set up in Suptask. Read more about how Assistants work to understand all use cases.

{% content-ref url="/pages/EMXzCysY1oz2JPFXI8gH" %}
[AI Assistants](/suptask-ai/ai-assistants.md)
{% endcontent-ref %}

***

### Troubleshooting

* **Authentication failed** - the API key is wrong or was deleted in BambooHR, or the company domain is incorrect. Check that the domain is only the subdomain, without `.bamboohr.com`.
* **Connected, but no data returned** - the access level of the user who generated the key doesn't cover the data you're asking for. Check it in **Settings → Access Levels**.
* **Some employee fields are missing** - those fields aren't included in the access level, or the scope is narrower than the employees you're asking about. Add the fields under **What this Access Level Can See**.
* **Who's Out returns nothing** - the time off categories aren't granted to the access level.
* **The Assistant can't create or update an employee** - the tool is set to **Off**, or the access level only has **View only** where **Edit** is needed.
* **A change waits and never happens** - the tool is set to **Ask** and no agent has approved it yet. Approve it on the ticket, or set the tool to **Auto** if it should run on its own.
* **The connector stopped working** - the API key may have been deleted, or the BambooHR user deactivated. Generate a new key, or reactivate the user, and update the connector.