Troubleshooting - BambooHR

Troubleshooting

For common issues that apply to all connectors — authentication failures, syncs stuck or not progressing, no documents indexed, stale permissions — see Troubleshooting - Enterprise Search Connectors.

Expected Company File is missing from search

Symptoms: A handbook or policy exists in BambooHR but does not appear in Enterprise Search.

Possible causes:

1. The file is not public in BambooHR.

2. The file’s creation date is outside the document-age window (default: last 2 years).

3. A File Category include/exclude filter omitted the file’s category.

4. The API key’s access level cannot see that Company Files category — including when the category was created after the access level was configured.

Resolution:

1. In BambooHR, confirm the file is shared with employees.

2. Check the file’s creation date against the connector’s document-age filter.

3. Review File Category filters on the connector and match the exact BambooHR category name.

4. Open the connector's custom access level and grant Access company files for that category. New categories must be added manually; they are not inherited automatically.

5. After correcting configuration, wait for the next incremental sync or click Sync now from Enterprise Search → BambooHR → Status.

Sync fails after repeated bad API key attempts

Symptoms: Syncs fail with permission or authentication errors even after you paste what looks like a valid key. BambooHR may temporarily disable API access after repeated use of an invalid key.

Possible causes:

1. Wrong company domain or API key.

2. Temporary BambooHR API lockout after repeated invalid authentication.

3. The API key’s owning user was disabled.

Resolution:

1. Verify Company Domain and API Key in the connector configuration.

2. Confirm the service user is still enabled in BambooHR and regenerate the API key if needed.

3. Wait out any BambooHR lockout period before retrying — repeated retries can extend the lockout.

4. Save the corrected configuration, then run Sync now.

Account employee limit errors from BambooHR

Symptoms: Sync fails with an account-level error related to employee limits (not ordinary throttling).

Possible causes:

1. The BambooHR account has reached its employee licence limit. BambooHR surfaces this differently from rate limiting.

Resolution:

1. Contact BambooHR to resolve the account employee limit.

2. Do not treat this as a temporary slowdown — waiting and retrying will not clear an employee-limit state.

Frequently asked questions

Common questions about sync frequency, deletions, audience filters, and throttling are answered in Troubleshooting - Enterprise Search Connectors. Security, privacy, and data questions are answered in Data & Security - Enterprise Search Connectors.

Q1. Why is a file I can see in BambooHR missing from search?
The connector only indexes files shared with employees, within the document-age window, and within any File Category filters you configured. The service account must also be able to see that Company Files category on its custom access level. Role-only visibility in BambooHR is not enough if the file is not shared with employees.

Q2. A new Company Files category was created — why are its files missing?
New categories are not automatically added to an existing custom access level. Open Settings → Access Levels, edit the connector's access level, grant access to the new category under Company Files, then wait for the next incremental sync (or run Sync now).

Q3. How do File Category filters work?
You can include and/or exclude BambooHR Company File categories by exact name. Names are case-sensitive and must match BambooHR. Filters only apply to categories the API key can already see. If no category filter is set, all categories visible to the API key are eligible (still subject to the share-with-employees gate and document age).

Q4. How long until a new handbook appears in search?
Typically within about an hour after the next incremental sync. The first full sync after setup may take longer depending on library size.

Q5. Does the BambooHR service account need administrator rights?
No. A read-only custom access level with Access company files (per category) and View on Work Email and Home Email under See About Other Employees → Personal → Contact is sufficient, including for document-level security.

Q6. Why does the connector need Work Email and Home Email?
Email is the identifier Simpplr matches BambooHR employees against for document-level security. The connector prefers Work Email and uses Home Email when Work Email is empty. Grant View only on those Contact fields — other personal fields are not required.