Skip to main content

​
After this article

You will be able to connect BambooHR to Lumos so BambooHR users sync into Lumos, and use BambooHR as your User Source (Source of Truth) for employment status.

​
Capabilities

How Lumos reconciles BambooHR accounts and statuses:
  • BambooHR accounts in Lumos represent BambooHR user accounts. By default, employees without a user account do not appear in Lumos, even if an employee record exists. Lumos Support can enable syncing of employees who have no login (contractors, terminated employees whose login was removed, and future hires). Their employee-record attributes, including Termination Date, then sync so End Date mapping and auto-offboarding work for them.
  • Account Status maps from BambooHR User Status: enabled → Active, disabled → Suspended. An employee whose hire date is in the future is Staged until the hire date passes (requires future-hire syncing, below).
  • Employment Status (only when BambooHR is set as the User Source / Source of Truth): if the user has an employee record, Lumos uses the employee record status. If not, Lumos uses the user status. Combined logic:
Note the edge case: a disabled user with an Active employee record still maps to Employment Status Active.

​
Required plan and roles

  • BambooHR plan: your company must be on the BambooHR Enterprise plan.
  • BambooHR role: the user account that creates the API key should be an admin that can view all users and all employee records, with permission to manage the lifecycle of all users. BambooHR API keys inherit the permissions of the user who creates them.
    • If the token-creating user cannot view all employee records, employee status information will be inaccurate for any employee they can’t view.
  • Tip: consider creating a dedicated BambooHR admin user for the integration and generating the key while logged in as that user, so the connection doesn’t depend on an individual employee’s account.
  • Permission scoping: there is no reduced-scope option. The key must come from an admin with full visibility for accurate syncing.

​
Read-only access vs provisioning

Is read-only possible? No. BambooHR API keys inherit the permissions of the admin who creates them, and there is no reduced-scope option. The key must come from an admin with full visibility and lifecycle permissions over all users for syncing to be accurate. What full provisioning requires. The same API key, created by an admin who can view all users and employee records and manage the lifecycle of all users. Consider creating a dedicated BambooHR admin user for the integration, as described above, so the connection doesn’t depend on one employee’s individual account. Watch out for. Suspending a user in Lumos requires the API key owner to still have lifecycle permissions over all users. If that admin is disabled or loses access, the key stops returning full data, and both suspend actions and syncing are affected. If the key-creating admin can’t view certain employee records, status information for those employees will be inaccurate instead of missing.

​
Instructions

Phase 1: Generate an API key in BambooHR
  1. Log into BambooHR and go to Settings.
  2. Under Account Settings, click API Keys.
  3. Generate a new API key (click Add New Key, name it, then Generate Key) and save the value (it is only shown once).
  4. Under Account Settings, click Account Info.
  5. Scroll to your BambooHR URL and note the subdomain (e.g. for lumos.bamboohr.com, the subdomain is lumos).
Phase 2: Connect in Lumos
  1. Find the BambooHR card in your Lumos integrations (reconnect an existing card or add a new one).
  2. Paste the subdomain into the Instance Name field.
  3. Paste the API key into the API Key field.
  4. Click Connect BambooHR.

​
Troubleshooting

Can’t connect the integration. Make sure you’re on the BambooHR Enterprise plan, and that the user who generated the API key can view and manage the lifecycle of all users in your BambooHR environment. Employee status looks wrong for some people. The API key inherits the creating user’s visibility. If that user can’t view certain employee records, status information for those employees will be inaccurate. Regenerate the key as a full-visibility admin. An employee is missing from Lumos. Employees who have no BambooHR user account (only an employee record) do not appear in Lumos unless syncing of employees without a login has been enabled for your tenant. Contact Lumos Support to enable it. Connection stopped working. BambooHR API keys belong to the user who created them. If that user is disabled or loses admin access, the key stops returning full data, so regenerate the key from an active full-visibility admin (or a dedicated integration user). The BambooHR field I want to map is missing from the Source Field dropdown. Lumos surfaces a fixed set of BambooHR fields for custom attribute mapping rather than every field on the employee record, so a valid BambooHR field can still be absent from the list. Recently added mappable fields include the employee’s location. This is not something you can enable from configuration on your side, and changing your Source of Truth to BambooHR does not expose additional fields either. If the field you need is not listed, contact Lumos Support and name the field and the use case so it can be considered for the mappable list. One field to be careful with when looking for a substitute: bestEmail returns the employee’s work email whenever one is on file and only falls back to a personal address when there is no work email, so it is not a reliable stand-in for a personal email field. An employee with a future hire date is not in Lumos yet. By default the BambooHR sync pulls employees who are current as of today, so people who have not yet started do not appear until their hire date passes. Lumos can instead sync future-dated hires ahead of their start date: contact Lumos Support to enable it (it also requires syncing employees who have no BambooHR user account, since a pre-hire has no login). Once enabled, a pre-hire appears as Staged until their hire date, after which they become Active, and their attributes sync ahead of day one so onboarding automation can act on them. Switching your Source of Truth to BambooHR. Identities are matched by email, so the main risk is a BambooHR record that does not match an existing Lumos identity and is therefore treated as a brand-new user. Before you promote BambooHR to priority 1:
  • Connect BambooHR, run a sync, and confirm the work emails coming from BambooHR match the emails on your existing identities.
  • Check for anyone who exists only in your current source and not in BambooHR (contractors are the common case), since those identities will no longer be fed by the new source.
  • Temporarily turn off automatic onboarding while you validate, and onboard manually in the meantime. Lumos does not re-onboard anyone who has already been onboarded, but a user whose record fails to match can look new and trigger onboarding.
  • If you use the Start Date trigger, spot-check start dates for long-tenured employees first. Lumos does not automatically onboard users whose start date is more than 14 days in the past, so an obviously wrong recent date is the case to look for.
  • Remap your other user attributes to BambooHR before you make the switch, then promote BambooHR to priority 1, re-sync, and spot-check a sample of users.
Note that changing your Source of Truth changes which system feeds your attributes. It does not make additional BambooHR fields available for mapping.