# Common Issues

## Connection issues

<details>

<summary>Invalid API key error when connecting</summary>

Double-check that you've copied the full API key from BambooHR — it's easy to accidentally miss a character. Also confirm you're using the correct company subdomain (the part before `.bamboohr.com` in your BambooHR URL). The subdomain is case-sensitive.

To regenerate a key: go to your BambooHR profile → **API Keys** → **Add New Key**.

</details>

<details>

<summary>Connection succeeds but no data loads</summary>

This usually means the API key belongs to a user without sufficient permissions. BambooHR API access is tied to the user's role — make sure the key was generated by an **admin** or a user with access to the entities you're trying to pull.

</details>

## Missing data

<details>

<summary>Time off requests return no results</summary>

Check the **start date** parameter in your data flow settings. By default it looks back 30 days — if you're expecting older records, use the date picker to set an earlier start date. Also verify the request statuses you expect (approved, pending, denied) exist within that date range in BambooHR.

</details>

<details>

<summary>Timesheet entries are empty</summary>

Timesheet data is only available if your BambooHR subscription includes **time tracking**. If your plan doesn't include this feature, the entity will return no data. Check your BambooHR plan or contact BambooHR support to confirm.

</details>

<details>

<summary>Custom reports return no columns or fewer fields than expected</summary>

The `custom_reports_fields` parameter requires field aliases that exactly match BambooHR's field name list. A typo or unsupported field name will silently drop that column. Run the **Meta fields streams** entity first to get a list of valid field aliases for your account, then update your custom report fields accordingly.

</details>

<details>

<summary>Terminated employees are missing from the directory</summary>

The Employees directory entity typically returns active employees only. BambooHR's API behavior for terminated employees depends on your account configuration. If you need terminated employee records, check whether your BambooHR account is set to include them — or use a Custom report with a status field filter.

</details>

## Permission errors

<details>

<summary>403 Forbidden error on specific entities</summary>

{% hint style="warning" %}
Even if your API key is valid, BambooHR restricts access to certain data based on the generating user's role. A 403 on a specific entity means that user doesn't have permission to view that data type.
{% endhint %}

To fix this, regenerate the API key using a BambooHR admin account, or ask your BambooHR admin to grant the user access to the relevant data.

</details>

## Data discrepancies

<details>

<summary>Headcount in Coupler.io doesn't match BambooHR reports</summary>

BambooHR's built-in reports may apply filters (e.g., employment type, status) that aren't applied by default in the Employees directory API. Check whether the BambooHR report you're comparing against excludes contractors, part-time staff, or employees in specific statuses — and apply equivalent filters in your Coupler.io data flow or destination.

</details>

## Rate limits

<details>

<summary>Data flow fails with a rate limit error</summary>

BambooHR enforces API rate limits per account. If you're running multiple data flows against BambooHR simultaneously, they may compete for the same rate limit budget. Stagger your scheduled syncs to avoid hitting limits, and avoid running manual runs during scheduled sync windows.

</details>