# Bamboohr
Connecting BambooHR gives SureCloud read access to your BambooHR account's employee directory, employment status records, custom field data, and time-off information. SureCloud uses BambooHR as the HR-authoritative source for employee lifecycle data — tracking hire dates, termination dates, and role changes to support evidence requirements around access provisioning and deprovisioning. SureCloud cross-references BambooHR records with connected identity providers to surface discrepancies between HR status and active system access.
{% hint style="info" %}
SureCloud connects to BambooHR using an API Key (Bearer Token) generated from a dedicated service account. BambooHR does not support OAuth 2.0 for API integrations.
{% endhint %}
## Authentication and setup
{% stepper %}
{% step %}
#### Create a dedicated service account in BambooHR
In BambooHR, navigate to **Settings → Access Levels** and create a custom access level named `SureCloud Read Only` with the following permissions set to **View** only (no Edit or Delete):
| Data area | Permission |
| --------------- | ------------------------------------- |
| Employee data | View |
| Personal data | View |
| Employment data | View |
| Job information | View |
| Compensation | View (if required for access scoping) |
| Time off | View |
| Custom fields | View |
Then navigate to **People → New Employee** and create a service account user (e.g. `surecloud-ccm@yourcompany.com`) and assign it the `SureCloud Read Only` access level.
{% hint style="warning" %}
Do not generate the API key from a personal BambooHR account. Tie it to the dedicated service account so that key rotation and access are independently managed.
{% endhint %}
{% endstep %}
{% step %}
#### Generate an API Key
Log in to BambooHR as the `surecloud-ccm` service account. Click the account name in the top-right corner and select **API Keys → Add New Key**.
* **Key name**: `SureCloud CCM`
Click **Generate Key** and copy the value immediately — it is only shown once.
{% hint style="warning" %}
Rotate this key every 90 days. Update the new value in **SureCloud → Integrations → BambooHR → Edit Connection** before the old key is revoked to avoid a data collection gap.
{% endhint %}
{% endstep %}
{% step %}
#### Identify your BambooHR subdomain
Your BambooHR API base URL uses your company subdomain in the format:
`https://api.bamboohr.com/api/gateway.php/{subdomain}/v1`
Your subdomain is the company-specific slug visible in your BambooHR portal URL (e.g. `https://yourcompany.bamboohr.com` → subdomain is `yourcompany`).
{% endstep %}
{% step %}
#### Enter credentials in SureCloud
In SureCloud, navigate to **Integrations → BambooHR → Connect** and provide:
* **BambooHR subdomain**
* **API Key**
Click **Test Connection**, then **Save**.
{% endstep %}
{% endstepper %}
## Endpoints
| API Call | Use Case |
| --------------------------------------- | --------------------------------------------------------------------------------------------------- |
| `GET /employees/directory` | Retrieve the employee directory with basic information for all active employees |
| `GET /employees/{id}?fields=...` | Read full employee record including hire date, termination date, job title, department, and manager |
| `GET /reports/custom` | Request a custom report to retrieve all employees including terminated, with specified fields |
| `GET /employees/{id}/time_off/requests` | Read time-off requests to identify employees on extended leave |
| `GET /meta/fields` | Enumerate available employee fields including custom fields |
| `GET /meta/tables` | List available data tables for structured field access |
## Pagination
The BambooHR API does not paginate the employee directory or custom report endpoints — all records are returned in a single response. The `GET /employees/directory` endpoint returns all active employees in one call.
For time-off request endpoints, BambooHR uses date-range filtering via `start` and `end` query parameters rather than pagination. SureCloud queries a rolling 90-day window per collection cycle.
{% hint style="info" %}
To retrieve terminated employees alongside active employees, SureCloud uses the custom report endpoint (`/reports/custom`) with the `includeInactive` parameter set to `true`. The employee directory endpoint returns only active employees by default.
{% endhint %}
## Required permissions
The `SureCloud Read Only` access level must have **View** permissions on all data areas listed in the setup steps. The API key inherits the permissions of the account that generated it — if the service account's access level is modified, the API key's effective permissions change immediately.
## Polling frequency
| Data type | Collection interval |
| -------------------------------------- | ------------------- |
| Employee records and employment status | 24 hours |
| Hire and termination dates | 24 hours |
| Job title, department, and manager | 24 hours |
| Time-off requests | 24 hours |
## Troubleshooting
Terminated employees are not appearing in SureCloud
The BambooHR employee directory only returns active employees. SureCloud uses the custom report endpoint with `includeInactive=true` to include terminated employees. If terminated employees are absent, the service account may lack the **View** permission on employment data, which is required to access inactive employee records.
Confirm the `SureCloud Read Only` access level includes **View** on **Employment Data** in **BambooHR → Settings → Access Levels → \[SureCloud Read Only] → Permissions**.
Custom fields are not appearing for some employees
Custom field visibility in BambooHR is controlled by access level permissions on a per-field basis. If the `SureCloud Read Only` access level does not have **View** permission on specific custom fields, those fields will be absent from the API response.
In **BambooHR → Settings → Access Levels → \[SureCloud Read Only]**, review the custom field section and confirm **View** is enabled for each field SureCloud needs to collect.
API key authentication is failing despite the key being correct
BambooHR API keys are authenticated using HTTP Basic Auth with the API key as the username and `x` as the password (a fixed placeholder). If SureCloud is sending the credentials in a different format, authentication will fail.
Confirm the API key was generated from the correct BambooHR subdomain and that the subdomain entered in SureCloud matches exactly. Subdomains are case-sensitive in the BambooHR API base URL.
Hire or termination dates are missing for some employees
Hire and termination dates are stored under the **Employment** data section in BambooHR. If these dates are absent, either the service account lacks **View** permission on employment data, or the dates have not been recorded for those employees in BambooHR.
In BambooHR, open the employee record and confirm the **Employment** tab contains a hire date and, for terminated employees, a termination date. If the data is present in the UI but absent from SureCloud, check access level permissions as described above.
BambooHR API reference
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://surecloud.gitbook.io/surecloud-docs/integrations/ccm-and-evidence-collection-integrations/bamboohr.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.