> ## Documentation Index
> Fetch the complete documentation index at: https://docs.truu.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Connect BambooHR

> Connect TruU IDV to BambooHR with an API key from a restricted user: the access level to create, the values to enter, and how to test the connection.

This page is for the BambooHR administrator connecting TruU IDV. When you finish, TruU can look up one employee at a time during verification, reading only the fields you allow.

## Before you start

* A BambooHR administrator who can create access levels and users.
* Your BambooHR company domain: the part before `.bamboohr.com` in your BambooHR address. For `acme.bamboohr.com` it's `acme`.
* The employee number of someone to test with.
* An **Owner** or **Admin** seat in TruU IDV.

## Restricted account

A BambooHR API key can do exactly what the user who created it can do. A key created by an administrator can read everything, including SSNs, pay and benefits. Create a dedicated user with an access level that can see only what TruU reads, and create the key as that user.

**1. Create an access level**

In BambooHR, open **Settings → Access Levels** and add a custom access level, for example "TruU integration". For all employees, give it view access (no edit) to:

* Legal first and last name, and employee number
* Date of birth and home address, if you match them during proofing
* Home email and mobile phone, if you use them in knowledge questions
* Employment status
* Any custom field you add as a TruU attribute

Leave everything else off, especially SSN (unless a knowledge question uses it), compensation, benefits, emergency contacts and dependents.

**2. Add a user with that access level**

From the access level, add a user. It doesn't need to be an employee. Use an address that can receive the BambooHR invite.

**3. Create the API key as that user**

Accept the invite and sign in as that user. Open your name, then **API Keys**, then **Add New Key**. Copy the key; BambooHR shows it once.

> [!NOTE]
>
> Field-level access is set in BambooHR, so a restricted user is the strongest control available. TruU also warns you after a test lookup if the key can read sensitive fields TruU doesn't use.

## Set it up

**1. Open BambooHR in TruU**

Go to **Settings → Directory** and, under **HR system**, choose **BambooHR**.

**2. Enter the details**

Enter the **Company domain** and the **API key**.

**3. Test and connect**

Enter an **Employee number** to test with and choose **Test and connect**.

**4. Review finding people and attributes**

By default TruU matches the directory's **Employee Id** to BambooHR's **Employee number**. Adjust it if needed, add any custom attributes, and choose **Save changes**. See [Finding people](https://docs.truu.ai/idv/connect/hr/overview.md#finding-people).

## Test it

Choose **Test lookup** on the BambooHR page at any time. TruU looks one person up and shows which fields came back as **Present** or **Missing**. A field that's **Missing** for everyone usually means the access level doesn't include it.

If the key can read sensitive fields TruU doesn't use, the result says so and names them. Switch to a key from a restricted user with **Rotate credentials**.

## How it works

* **Lookup.** TruU finds the person by employee number (or work email, or BambooHR's internal ID), then requests only the fields a factor needs for that verification.
* **Fields.** BambooHR's field list is used to offer custom attributes. Custom fields may appear with a name (for example `customShirtsize`) or a numeric ID; both work.
* **Sign-in.** The API key is sent as the BambooHR username over HTTPS and stored in a managed secrets service.

> [!WARNING]
>
> If BambooHR can't answer, or you disconnect it, checks that read BambooHR are skipped and verification continues. See [When HR is unavailable](https://docs.truu.ai/idv/connect/hr/overview.md#when-hr-is-unavailable).

## Troubleshooting

| Symptom | Cause | Fix |
| - | - | - |
| **BambooHR rejected the sign-in** | The key was revoked, or its user was deactivated | Create a new key and use **Rotate credentials** |
| Date of birth or address is **Missing** | The access level can't see them | Add them to the access level |
| **No match** for a known employee | The employee number in your directory differs from BambooHR's | Compare both values; add format steps such as **Strip leading zeros** |

## Related

* [Connect your HR system](https://docs.truu.ai/idv/connect/hr/overview.md)
* [Knowledge](https://docs.truu.ai/idv/factors/knowledge.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.