The Definitive Guide to Migrating to BambooHR

BambooHR LLC was founded by Ben Peterson and Ryan Sanders in 2008 and is headquartered in Lindon, Utah ¹. The platform began as a small-business HRIS and has since added an applicant tracking system, performance management, time tracking, benefits administration, and a US-focused payroll product, all sitting on top of a single employee record.

The typical BambooHR customer is a US-based company between 25 and 1,500 employees that wants a single source of truth for employee data without standing up a Workday-class implementation team. Pricing shifts from a flat $250/month under 25 employees to a per-employee-per-month model above that, with payroll, time tracking, performance, and benefits administration each priced as add-ons.

The shapes of migration that actually land on BambooHR tend to fall into four patterns. First, spreadsheet exits: a growing company replacing Google Sheets, Excel and a Dropbox folder of signed PDFs with a real employee system of record. Second, legacy HRIS replacements — Paychex Flex, ADP Workforce Now, Paylocity, UKG Ready, Zenefits, Gusto-only setups — driven by total cost of ownership or admin overhead.

Third, upmarket-tool downgrades — a company that bought Workday, UKG Pro or SAP SuccessFactors for a future it never reached, scaling back to a system its HR team of two can actually operate. Fourth, M&A integration, where an acquired entity runs on a different HRIS. A spreadsheet exit usually has clean scope but no historical audit trail; a Workday exit has rich history that does not move across.

What makes migrating *to* BambooHR easier than the category average is the CSV importer itself — a single Import Tool sits inside the product, accepts Excel and CSV files, and lets HR admins map columns against the BambooHR field dictionary without code ⁴. Custom Dashboards on the Elite tier can ingest CSV uploads up to 500,000 rows per dataset ⁵.

What makes it harder than the average is the lack of any undo button on the Import Tool — every official BambooHR training begins with that warning ⁴⁶ — and the fact that historical tables for compensation, job info and employment status are effective-dated, so loading a single current row erases the timeline you might have spent two weeks reconstructing in Excel.

Time Off accruals, performance review cycles, document templates and workflow automations do not import — they are rebuilt inside the product after the employee data lands. Teams that scope for that work up front finish on time; teams that assume parity do not.

Teams that scope for the rebuild work up front finish on time; teams that assume parity do not.

BambooHR is built around a single root object — the Employee — with a set of tabular sub-tables hanging off it for data that changes over time. Most other concepts in the platform are either fields on the employee, rows on one of those tables, or related objects (time off, files, goals) keyed by employee ID.

Before you can map a field on the source side, you need to know exactly which destination table the row belongs on, what fields it requires, and which value will serve as the matching key. The table below summarises the objects you will touch in a typical migration.

The Employee record is the canonical primary key for the whole system — BambooHR assigns a numeric Employee ID on creation, and every file upload and table row is keyed by it ⁷. The Import Tool can also match on a custom Employee # field, work email, or SSN if you flag the column as the unique identifier during mapping — rows with the same value collapse into one record ⁴.

Effective-dated tables — Job Info, Compensation, Employment Status, plus any Custom Tables — are the most consequential modelling decision in a BambooHR migration. Each row carries an effective date and BambooHR uses the most recent row as the *current* value while preserving the timeline behind it ⁷. Load one row and you lose the history; load every dated row and the profile reconstructs every promotion, raise and leave on day one.

Custom fields are added in Settings → Account → Customize → Tabs/Fields, with a fixed set of supported types: text, multi-line text, number, currency, percentage, date, single-select list, checkbox, employee, email, EIN, country, state ⁸. List-type fields store internal values that must exist in the field's option set before import — adding a value via the Import Tool fails, so you pre-create options through the Customize UI ⁸⁹.

Relationships in BambooHR are modelled implicitly. The org chart is derived from the Supervisor (Reports To) field on each employee, which must resolve verbatim to another employee's record — name-based matching is the default, but Supervisor Email or a Supervisor ID calculated field is more reliable for hierarchy builds ¹⁰. Every employee needs a supervisor except the top-level leader, whose Reports To is left blank to mark the tree's root ¹⁰.

Access Levels — Account Owner, Full Admin, HR Admin, Manager, Employee and optional Custom Access Levels — control which fields and tables each user can view and edit, and are configured under Settings → Access Levels ¹¹. Access Levels must exist before the user accounts they will be assigned to; otherwise newly imported employees default to the standard Employee access level with no way to see compensation, performance or document data even on their own profile.

The single best predictor of a clean BambooHR migration is how much work you do on the source side before the first import button is pressed. BambooHR's own Import Tool training warns explicitly that the tool has no undo button ⁴, and the fix is almost always pre-processing rather than post-cleanup.

The Import Tool has no "undo" button — you must watch the training and go through the Import Tool Tutorial before using it.

Treat the source export as raw material that needs to be shaped to BambooHR's expected formats — dates rewritten to yyyy-mm-dd, currency stripped of thousands separators, country names spelled out, list-field values aligned to BambooHR's option sets, and every supervisor pointer resolved to an actual person in the file.

Source-side prep

• Audit and dedup the source database before export. Two employee rows with the same work email or SSN collapse into one record on import and the wrong row may win — sort by hire date and termination date and pick a single source of truth per person.
• Normalise dates to yyyy-mm-dd for every column the importer will touch — date of birth, hire date, termination date, every Job Info / Compensation / Employment Status row ⁸. The Import Tool tolerates a few formats; programmatic loads require strict ISO.
• Convert list values for every dropdown field — Employment Status, Department, Division, Location, Job Title (if you keep it as a list), EEO Job Category, marital status, custom lists. Each value must already exist in the BambooHR option set or the row is rejected ⁸⁹.
• Stamp a stable Employee # on every record in the source export — a UUID, source primary key, or the existing HRIS employee ID — so re-runs match deterministically and the original audit trail is reachable post-cutover.
• Decide what is in scope for historical compensation, job info and employment status. Each effective-dated row counts as one row in the import file, and re-creating ten years of raise history for 500 employees is a 50,000-row Compensation file even before you touch demographics.

Destination-side prep

• Customise the schema first. Walk every Tab and every Field under Settings → Account → Customize → Tabs/Fields and add the custom fields, custom tables, and list option values you intend to map to — the Import Tool maps to fields that already exist ⁴.
• Pre-create Employment Statuses that match your real workforce — Active, Inactive, Leave of Absence, Terminated, plus any custom status (Contractor, Intern, Seasonal). Statuses tie to ACA Status Category calculation and to whether the employee shows up in directory / payroll ⁸.
• Build Time Off categories and policies before importing balances — category name (Vacation, Sick, PTO, Parental Leave), accrual policy, carryover rules, holiday calendar. Balances are imported as a separate file once the categories and policies are in place.
• Provision Access Levels before users — Account Owner, Full Admin, HR Admin, Manager, plus any Custom Access Levels with field-level permissions. SSO via Okta or Microsoft Entra ID can be staged ahead of cutover but enabled at go-live ¹².
• Define Custom Tables that mirror your source data shape — Education, Certifications, Licenses, Visa Information — with the columns and field types each will hold. Custom Tables cannot be re-typed retroactively after data is loaded.

People prep

Cutover only works if humans cooperate. Lock a source-system freeze window — typically a payroll-period boundary — and communicate it to HR, Payroll, IT and every people manager. BambooHR's own switch-software guide recommends assembling an internal team with a senior project lead who has change-management experience ¹³. A 50-employee company often finishes in two to four weeks; a 500-employee project with payroll, performance and benefits add-ons runs two to three months. Build the human runway accordingly.

BambooHR exposes several load paths and the right one depends on dataset size, table mix, and whether you need to re-run idempotently. The native Import Tool covers most one-shot migrations under a few thousand employees. Programmatic loads handle repeatable, and large loads — especially anything that touches effective-dated tables. Third-party tools sit on top of both and add staging, transformation and dedup layers.

Native Import Tool

The native import lives at a unique per-account URL (visible inside the Import Tool Tutorial in the product) and opens from the BambooHR partner / training portal ⁴. It accepts Excel (.xls, .xlsx) and CSV (.csv) files, walks the admin through column mapping against the BambooHR field dictionary, and previews the first rows before commit ⁴. The Hours Importer and Custom Dashboards each have their own dedicated upload flows ¹⁴⁵.

Two operational constraints define how teams actually use it. First, there is no undo — every BambooHR training begins with a single-row test import ⁴⁶. Second, the Import Tool maps to fields that already exist in your account; if a source column has no destination field, the importer will not silently create one — add the field through Customize first.

The right call: the Import Tool for one-shot employee loads under a few thousand records, for Hours imports, for any per-employee field refresh, and as the primary handoff format for BambooHR Onboarding Specialists during paid implementation.

Programmatic loads

Programmatic loads are the path for repeatable, large, or history-heavy datasets. They let you create employees, post effective-dated table rows for Job Info and Compensation, upload documents, and manage list-field options without touching the Import Tool UI ⁹⁷. Official PHP and Python client libraries ship from BambooHR with fluent client builders and typed models ¹⁶. Throughput ceilings are not published as a fixed number; BambooHR returns Retry-After headers when you exceed the per-account ceiling and the documented pattern is to back off on the header value ¹⁸.

Effective-dated tables are the programmatic path's strength relative to the UI importer. A dated-row write takes a single row and adds it to the history without disturbing existing rows, and an update is keyed off the row ID ²⁰. Deletions return a conflict response if the row has pending approval changes or is tied to an active pay schedule ²⁰ — both conditions you need to handle when re-running history loads.

Third-party staging tools

Tools like Fivetran, Airbyte, Portable, Skyvia and Workato all ship BambooHR connectors. Their role in a migration is rarely the migration itself — it is the staging layer that lands source HRIS data into a warehouse, the transformation layer that converts list values and date formats, and the ongoing-sync layer that takes over once the one-time migration is complete. Workato in particular ships dedicated Time Off action recipes that the Import Tool cannot replicate.

For one-time migrations, the value is in repeatability under failure; for ongoing syncs to a data warehouse or a downstream payroll provider (Gusto, ADP, Paylocity), they become the system of integration.

Mapping is where every migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether the org chart renders on day two, whether PTO accrues correctly on day five, and whether your managers trust the data on day thirty.

Work top to bottom of the import order: Employees first (root record), then effective-dated tables (Job Info, Compensation, Employment Status), then Time Off categories and balances, then performance + compensation history, then documents, then Custom Tables and Hiring data.

Employee records and demographics

PTO balance accruals, carryover and holiday calendars

Time Off is the most platform-specific subsection of any HRIS migration. In BambooHR you must create the categories (PTO, Sick, Vacation, Parental, Bereavement) and the policies that accrue into them before you import any balances ²⁶. Each policy carries an accrual schedule (monthly, per-pay-period, lump-sum, anniversary), a carryover cap, a negative-balance allowance, and a tenure-based accrual rate table.

Balances are imported as adjustments through the Adjust Balance flow per employee per category, in the UI or programmatically. The number you import is the *current balance as of the import date* — it is not historical accrual, it is a starting line. The accrual engine then ticks forward from that balance using the policy. Freeze accruals in the source, export balances on the freeze date, and import as same-day adjustments ²⁷.

Holiday calendars are per-location and configured at Settings → Time Off → Holidays before any time-off requests are created. Custom carryover rules — for example California sick leave caps — are encoded in the policy itself, not in the imported data.

Effective-dated history — Job Info, Compensation, Employment Status

These three tables are the audit trail of every employee's career. The Job Info table holds dated rows for job title, department, division, location, employment type and supervisor. The Compensation table holds dated rows for pay rate, pay type (Salary/Hourly), pay schedule, overtime status and change reason. The Employment Status table holds dated rows for Active, Leave of Absence, Terminated and any custom statuses you defined.

By default programmatic reads return only currently effective values; pass onlyCurrent=false on the employee read to include future-dated and historical values ⁷. This matters for reconciliation — if you compare a freshly imported employee against the source export using the default response, you will think 12 years of compensation history vanished when in fact it is sitting in the historical table, just hidden behind the default flag.

Compensation history — bonuses, equity, raises

Beyond the Compensation table, BambooHR captures one-off compensation events as fields on the employee — bonusAmount, bonusDate, bonusReason, bonusComment for the *most recent* bonus only ²⁸. For full bonus and equity history you have three options: (1) load each bonus as a Compensation row with a "Bonus" change reason if it changes base rate, (2) create a Custom Table called "Bonus History" or "Equity Grants", or (3) import only the most recent bonus and archive the rest.

Compensation reports are tier-gated — the standard Compensation report is available on Advantage and above, and field-level access to the Compensation table is gated by Access Level ¹¹. Build your Custom Access Levels before importing compensation history or managers will land in a system where they cannot see the data they need to make pay decisions.

Performance history — goals, assessments, 360s

Performance Management is an add-on module with its own data model. Goals are objects keyed by employee with title, status (status-inProgress, status-completed, status-closed), due date, completion percentage and attachments, with reads capped at 50 results per page ²⁹³⁰. Assessments — self, manager, peer and 360 — are bound to a review cycle and template that you configure inside the product before any review can be loaded.

Historical performance reviews from another HRIS rarely round-trip cleanly. The common pattern is: load only the current active goals programmatically, or attach a per-employee PDF "Performance Archive" document containing prior review summaries to the Employee Files section. Pure inline migration of free-text reviews into BambooHR's structured templates is a manual exercise that consumes weeks of HR time and is usually scoped out.

Document storage per employee

Signed offers, NDAs, performance docs, I-9s, W-4s, visa paperwork all live in Employee Files, organised into per-employee folders and sub-sections (categories) you define under Settings → Files ³¹. Upload is via the Documents tab in the UI or programmatically with the file binary, a fileName, a category ID and an optional share flag determining whether the employee sees the file on their own profile ¹⁹.

Hard limits to plan around: individual files cap at 20 MB on upload ¹⁹, and the per-employee storage allowance is published as 1 GB by BambooHR support. For larger document estates (scanned legal files, large performance archives), the pattern most teams adopt is: keep originals in S3 or Google Drive, store a deep link in a custom URL field on the employee record, and only inline-upload the most recent or most-referenced subset.

Org chart, reporting lines and divisions

The org chart in BambooHR is computed dynamically from the Supervisor field on each employee — there is no separate Org Chart object to import ¹⁰. Every employee must have a supervisor assigned except the top-level leader, whose Reports To field is left blank to mark the root. The most reliable mapping uses Supervisor Email rather than supervisor name, because name matching breaks on duplicate names and the importer cannot resolve which Sarah Chen is meant ¹⁰.

Department and Division are independent list fields on the employee, not hierarchical objects — you can have a Sales department in the Americas division and a Sales department in the EMEA division, but the platform sees four list values, not a two-level hierarchy. Location is similarly a flat list. Plan to import supervisors *after* the root employee load so the lookup resolves to existing employee records.

Audit trail, ownership and original timestamps

Standard createdDate, lastChanged and the per-table id values are BambooHR-managed system properties — they are stamped on insert and cannot be overwritten during import ⁷. If you need to preserve the original audit trail, the pattern is to create two custom fields on the Employee, *Legacy Hire System* and *Legacy Employee ID*, and populate them from the source export, plus a custom Notes field per effective-dated row for change-reason narratives that the source carried.

Ownership during import works only if Access Levels and user accounts exist at the moment of import — managers referenced in the Supervisor field must already exist as employees, and Custom Access Level grants must already be defined or the imported employee defaults to the standard Employee level with no visibility into their own compensation, performance or document history ¹¹.

Validation is the bridge between the import finishing and managers being allowed in. Most BambooHR implementations follow a three-stage validation: a pilot load of 10 to 20 employees with stakeholder spot-checks, the full load with real-time monitoring of record counts and supervisor-chain integrity, and a 30-day post-migration data-quality audit. The most reliable signal is having department heads verify their own teams — they know what right looks like better than any reconciliation script.

Build a reconciliation queries spreadsheet that compares source and destination on each of these counts. Anything outside a 0.5 percent variance gets investigated before users get login access.

• Total active employees imported vs source — minus deliberately excluded terminated rows older than your retention scope.
• Employees per department / division / location vs source — a non-trivial variance usually signals a list-value mismatch or a typo in the source data.
• Total Job Info / Compensation / Employment Status rows per employee vs source effective-dated history — confirm the history did not collapse to a single current row.
• Sum of base salary across active employees vs the source payroll register — a dollar variance signals a currency-precision drop or a missed Compensation row.
• Org chart depth and width — count employees per level and confirm the top-level leader is the only employee with a blank Reports To field.
• PTO balances by category vs the source freeze-date export — confirm starting balances landed correctly per employee per category.
• Employee Files count and total bytes per employee — confirm large attachments did not silently fail against the 20 MB / 1 GB caps ¹⁹.
• Access Level distribution — GROUP BY accessLevel and confirm no manager landed at the default Employee level.

On top of reconciliation, run a manual spot-check protocol: pick 30 random employees across departments and verify each field against the source UI. Pick five executives, five managers and five individual contributors, and trace the full profile — compensation history, job info history, supervisor, direct reports, PTO balances, document folder. If a non-trivial discrepancy shows up in three or more of the 30, halt the load, fix the root cause, and re-import the affected employees by Employee #.

Rollback is the hardest part. BambooHR does not ship a bulk-undo for the Import Tool ⁴⁶, and the closest equivalent is per-table delete — row-by-row, and it returns a conflict response if the row has pending approvals or is tied to an active pay schedule ²⁰.

The practical rollback strategy: export everything to S3 before the import starts, stamp every imported employee with a *Legacy Hire System* and *Migration Batch ID* custom field, and if catastrophe strikes, bulk-deactivate by that batch ID and re-import from the cleaned source.

Cutover sequencing: (1) source goes read-only on a payroll-period boundary and HR is notified; (2) final delta export captures everything that changed during the test-import window; (3) delta is imported; (4) reconciliation runs against the source freeze-date snapshot; (5) Access Levels and SSO are enabled; (6) managers get login access and a 48-hour hyper-care window with the migration lead on call; (7) source decommission is scheduled for 30 to 90 days out, never the same day.

The BambooHR Partner Program runs a Marketplace of certified implementation partners, payroll-integration partners and reseller partners reachable through the BambooHR Partners portal. Partners with explicit HRIS-migration practices — Paychex-to-BambooHR, ADP-to-BambooHR, Zenefits-to-BambooHR, spreadsheet-to-BambooHR — tend to ship cleaner than generalist HR consultancies, because the failure modes are platform-specific.

BambooHR also runs an in-house Onboarding service that ships with a one-time implementation fee on every new contract, covering initial setup, the first employee data migration, and custom configuration. Third-party implementation partners typically add a further $2,000 to $8,000 in one-time costs on top of the BambooHR onboarding fee for larger or more complex projects.

On the ETL and iPaaS side, Fivetran, Airbyte, Portable, Skyvia and Workato all have BambooHR connectors. Their role in a migration is rarely the migration itself — it is the staging layer that lands source HRIS data into a warehouse, the transformation layer that converts list values and date formats, and the ongoing-sync layer that takes over once the one-time migration is complete.

Workato is common where the migration is bundled with Slack-driven Time Off workflows; Airbyte and Fivetran are common picks for warehouse-first analytics teams.

Managed-migration cost ranges vary widely. A clean spreadsheet-to-BambooHR move of under 100 employees with no historical effective-dated rows and standard fields often lands inside the BambooHR onboarding fee with no third-party partner needed. A 500-to-2,000-employee project with multi-year compensation history, custom tables, document migration and Hiring (ATS) module rebuild typically runs $8,000–$40,000, with the upper end driven by employee count, custom-field complexity, historical-data depth and the number of downstream integrations that need rebuilding rather than re-pointed.

For teams that want to outsource the migration end-to-end, FlitStack specialises in BambooHR migrations and handles the field mapping, effective-dated history preservation, PTO balance reconciliation, document migration and Access Level configuration described in Sections 5 and 7 of this guide. Pricing is fixed-fee, based on employee count and source HRIS, with separate line items for Custom Tables and historical Compensation depth so the scope is transparent before signature.

This is one of several legitimate paths — the right choice for any given team depends on whether they want a BambooHR-certified implementation partner, the in-house Onboarding service, an iPaaS-first approach, or a specialist migration vendor. Explore FlitStack →