# BambooHR HRIS directory sync

<!-- Generated by scripts/generate.ts. Do not edit. -->

Connect BambooHR in this setup, and we read your employee directory every few minutes.

:::note[Verification]
Verified on a real BambooHR tenant on 2026-11-09.
:::

The values in braces, such as `{acs_url}`, are specific to your connection. The setup link from the application you are connecting shows them with a copy button. The same steps appear there.

## Steps

<ol class="idp-steps">

<li class="idp-step">

<a id="account"></a>

### Choose who connects

Connect as a BambooHR user who can see every employee you want to sync. The connection reads only the people that user can see, so a user with limited access syncs only part of the directory.

</li>

<li class="idp-step">

<a id="connect"></a>

### Connect BambooHR

Select Connect BambooHR and enter your company domain, the first part of your BambooHR address: for https://acme.bamboohr.com it is acme. A page from OhAuthCat names the organization this directory belongs to; check it, then select Continue. The connect link lasts 30 minutes; if it expires, select Connect BambooHR again. You come back to this setup when BambooHR is done.

Fixes: [`directory_source_oauth_state_invalid`](/errors/directory_source_oauth_state_invalid/), [`directory_source_oauth_expired`](/errors/directory_source_oauth_expired/), [`directory_source_oauth_confirm_required`](/errors/directory_source_oauth_confirm_required/)

</li>

<li class="idp-step">

<a id="approve"></a>

### Approve access

BambooHR asks "Share access with OhAuthCat Directory Sync?" and lists read-only access under OpenID Claims (User Email Address, Authenticate with BambooHR), Employee (Full Profile (Non-Sensitive), Contact Information, Job Information, Full Name, Employee Directory) and Miscellaneous (Persistent Access). Approve it. If a permission is missing, the connection is refused with a missing permission error; select Connect BambooHR again.

Fixes: [`directory_source_scope_missing`](/errors/directory_source_scope_missing/)

</li>

<li class="idp-step">

<a id="first-sync"></a>

### Wait for the first sync

The first sync starts right away. After that we read BambooHR every 5 minutes; after a failure we wait longer between tries, up to an hour.

</li>

<li class="idp-step">

<a id="who"></a>

### Know who is synced

We read the full employee list on every sync. People BambooHR no longer returns are removed from the directory, and changes to names, titles or departments are updated.

</li>

<li class="idp-step">

<a id="reconnect"></a>

### Connect again if access is removed

We keep the connection alive on our own. If BambooHR access is revoked, syncs stop with an invalid credentials error; select Connect BambooHR again.

Fixes: [`directory_source_credentials_invalid`](/errors/directory_source_credentials_invalid/)

</li>

<li class="idp-step">

<a id="api-key-moved"></a>

### Connect again if you used an API key

We no longer accept BambooHR API keys. A directory set up with an API key stops syncing until you select Connect BambooHR and approve access; the directory and its people stay as they are.

Fixes: [`directory_source_method_unavailable`](/errors/directory_source_method_unavailable/)

</li>

</ol>

## Sources

- [Getting Started With The API (BambooHR)](https://documentation.bamboohr.com/docs/getting-started), read on 2026-10-29
