---
title: "Migrate to BambooHR: HRMS Migration Guide & Service"
description: "Migrating to BambooHR? Import limits, the full migration checklist and every source FlitStack AI moves into BambooHR, with history and rollback."
url: "https://flitstack.ai/migrations/hrms/bamboohr"
---

# Migrate to BambooHR

BambooHR is a small-and-mid-market HRIS whose import model rewards teams that pre-define employment statuses, list field values, and access levels before a single employee row is uploaded.

Short answer

FlitStack AI migrates employees, payroll, and benefits into BambooHR from 200+ HR systems, including Greenhouse, Rippling, Keka, Personio. Every field is mapped to BambooHR's objects, history and associations come across, the BambooHR setup is configured alongside, and the whole migration stays reversible in one click.

![](https://flitstack.ai/images/authors/aditya-kumar.webp)By [Aditya Kumar](https://flitstack.ai/about/aditya-kumar) Updated November 5, 2026

[Get a quote ](https://flitstack.ai/contact) [See every source →](https://flitstack.ai/migrations/hrms/bamboohr#sources-list)

![](https://flitstack.ai/images/illustrations/pair-stage.webp)

From Any source ![](https://flitstack.ai/platforms-trim/greenhouse.webp) ![](https://flitstack.ai/platforms-trim/rippling.webp) ![](https://flitstack.ai/platforms-trim/keka.webp)

Destination BambooHR ![](https://flitstack.ai/platforms-trim/bamboohr.webp)

Greenhouse Rippling Keka Personio Crelate

200+ sources mapped into BambooHR

## Systems we move into BambooHR

The HR systems teams most often move from. Each page shows what moves, the field mapping and what to watch for.

[![](https://flitstack.ai/platforms-trim/greenhouse.webp) Greenhouse to BambooHR](https://flitstack.ai/migrations/hrms/greenhouse/to/bamboohr) [Rippling to BambooHR](https://flitstack.ai/migrations/hrms/rippling/to/bamboohr) [![](https://flitstack.ai/platforms-trim/keka.webp) Keka to BambooHR](https://flitstack.ai/migrations/hrms/keka/to/bamboohr) [Personio to BambooHR](https://flitstack.ai/migrations/hrms/personio/to/bamboohr) [Crelate to BambooHR](https://flitstack.ai/migrations/hrms/crelate/to/bamboohr) [![](https://flitstack.ai/platforms-trim/workable.webp) Workable to BambooHR](https://flitstack.ai/migrations/hrms/workable/to/bamboohr)

## What BambooHR supports, and where its import tools stop

- Lowest friction entry point for SMBs moving off spreadsheets — intuitive interface means most teams are functional within days, not weeks.
- Consolidation value: BambooHR merges ATS, onboarding, HR records, time-off, and payroll into a single pane of glass that employees never need to leave.
- Volume discounts applied automatically by headcount, so pricing scales predictably as the company grows without renewal negotiations.
- BambooHR reports most customers go live in four to six weeks, making it a realistic commitment for under-resourced HR teams.

**REST only** API key (Basic Auth header)

**Rate limits** Not publicly documented; BambooHR reserves the right to throttle with 503 responses

| Object                        | Support | Note                                                                                                                                                                                                                                                                                                                     |
| ----------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Employees                     | full    | The central entity in BambooHR. Each employee gets an immutable, company-scoped ID. We map all standard fields (name, contact, employment status, hire date, termination date, supervisor link) and flag any custom employee fields for value-mapping against the destination schema.                                    |
| Job Information               | full    | BambooHR stores division, department, job title, employment type, and location as first-class attributes on the Employee record. We preserve these as-is and handle renames where the destination uses different terminology (e.g., 'Department' vs. 'Business Unit').                                                   |
| Compensation                  | full    | Pay rate, pay type (salary/hourly/exempt), currency, and pay frequency are native fields. Levels and Bands (compensation grades) can be exported via CSV and imported back, but we treat them as supplemental compensation context rather than standalone records.                                                       |
| Time-Off                      | full    | Requests, balances, and policies are first-class objects. We map accrued balances as effective-dated values, and time-off types as categories. The export of Timesheet Entries and Time-Off Schedule reports includes separate Amount and Units columns added in a 2025 product update.                                  |
| Benefits Administration       | mapped  | Benefits enrollment data is stored per employee but the schema is highly customer-specific. We map what is present in the export report but flag that not all benefit plan details (carriers, coverage tiers, effective dates) are guaranteed to export cleanly without custom field handling.                           |
| Applicants (ATS)              | mapped  | BambooHR's applicant tracking stores candidates, applications, job postings, and pipeline stages. Pipeline stage names and custom application fields vary by account, so we map stage-to-stage manually and flag any custom fields that lack a destination equivalent.                                                   |
| Onboarding                    | mapped  | Onboarding tasks, checklists, and document requests are tied to new hires. The schema does not expose a standalone onboarding object via the standard report export; we reconstruct the onboarding state from the employee's onboarding task list and document completion flags.                                         |
| Custom Employee Fields        | mapped  | BambooHR is highly customizable. Any field not in the standard schema is a custom field with its own field type. We inventory all custom fields during scoping, validate types against the API field type reference (bool, currency, date, country, etc.), and apply type coercion where the destination schema differs. |
| Documents                     | mapped  | Documents attached to employee records (offer letters, contracts, signed forms) are accessible via the API. We flag document retention as a manual step or optional add-on since document binary storage and access controls vary significantly between source and destination.                                          |
| Performance Management        | mapped  | Performance reviews, goals, and review cycles exist as distinct modules but are not fully exposed in the standard employee export. We map review completion status and scores where the report exposes them and note that review history may require supplemental API calls.                                             |
| Reports (Standard and Custom) | full    | BambooHR's report engine is the primary export mechanism. Standard and custom reports can be downloaded as CSV or Excel. We use the report export as the foundation of the migration dataset and supplement with API reads for real-time fields not included in saved reports.                                           |
| Payroll Data                  | mapped  | Pay stubs, tax withholding, and journal entries are stored in BambooHR Payroll. Tax filing history and pay stub PDFs are not directly accessible via the standard export API; we handle payroll records as supplemental mapping subject to the destination's payroll module capabilities.                                |

## The BambooHR migration guide

## Why teams migrate to BambooHR

*The four shapes a BambooHR migration takes, and what makes the platform easier — or harder — than the category average.*

BambooHR LLC was founded by Ben Peterson and Ryan Sanders in 2008 and is headquartered in Lindon, Utah[1](https://flitstack.ai/migrations/hrms/bamboohr#source-1). 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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4). Custom Dashboards on the Elite tier can ingest CSV uploads up to 500,000 rows per dataset[5](https://flitstack.ai/migrations/hrms/bamboohr#source-5).

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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4) [6](https://flitstack.ai/migrations/hrms/bamboohr#source-6) — 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.

## The BambooHR data model you need to map into

*Employees, tables, custom fields and access levels — the destination schema decoded.*

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.

| Object                           | What it stores                                                                 | Required                                                  | Tier                                                     |
| -------------------------------- | ------------------------------------------------------------------------------ | --------------------------------------------------------- | -------------------------------------------------------- |
| Employees                        | The root record — personal info, employment status, contact details            | First name, last name, employee number or work email      | All tiers                                                |
| Job Info table                   | Effective-dated rows for job title, department, division, location, supervisor | Effective date, job title (one row per change)            | All tiers                                                |
| Compensation table               | Effective-dated salary, pay rate, pay schedule, change reason                  | Effective date, pay rate, pay type (Salary/Hourly)        | All tiers                                                |
| Employment Status table          | Effective-dated rows for Active, Leave, Terminated and custom statuses         | Effective date, employment status                         | All tiers                                                |
| Time Off categories + balances   | PTO, sick, vacation, parental — policies, accruals, requests, balances         | Category name, policy, accrual settings (set per company) | Core (advanced policies on Advantage+)                   |
| Performance (Goals, Assessments) | Goals, self/manager/peer assessments, 360 feedback                             | Employee ID; review cycle defined first                   | Performance Management add-on                            |
| Employee Files                   | Per-employee documents organised by file section/category                      | Employee ID, file section ID, file binary                 | All tiers; 1 GB / employee storage allowance             |
| Hiring (ATS)                     | Jobs, candidates, applications, hiring stages, feedback                        | Defined separately; not part of core employee import      | Hiring add-on                                            |
| Custom Tables                    | Per-employee multi-row data (Education, Certifications, Licenses)              | Effective or table date, defined columns                  | All tiers; per-account custom-table count varies by plan |

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[7](https://flitstack.ai/migrations/hrms/bamboohr#source-7). 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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4).

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[7](https://flitstack.ai/migrations/hrms/bamboohr#source-7). 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[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8). 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[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8) [9](https://flitstack.ai/migrations/hrms/bamboohr#source-9).

| Field type                     | Limit                                        | Notes                                                                                                                                     |
| ------------------------------ | -------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| Text / multi-line text         | Free-form string                             | Use sparingly — text fields cannot be reported on as enums                                                                                |
| Number / currency / percentage | Numeric, period decimal                      | Currency uses period as decimal point; no thousands separators[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8)                 |
| Date                           | yyyy-mm-dd                                   | ISO format required for programmatic loads; UI rewrites locale-specific values[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8) |
| List (single-select)           | Option set defined first                     | Import fails if the value isn't in the option list[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8)                             |
| Checkbox / bool                | yes / no / true / false                      | Case-insensitive on import; everything else defaults to unchecked                                                                         |
| Country / state                | Must match BambooHR country list             | Use full country name ("United States"), not ISO codes[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8)                         |
| Employee (lookup)              | References another employee                  | Used for supervisor / manager fields; resolves to Employee ID                                                                             |
| Custom Tables                  | Per-account cap; rows per employee unlimited | Education, Certifications, Licenses, custom multi-row data                                                                                |

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[10](https://flitstack.ai/migrations/hrms/bamboohr#source-10). Every employee needs a supervisor except the top-level leader, whose Reports To is left blank to mark the tree's root[10](https://flitstack.ai/migrations/hrms/bamboohr#source-10).

**500,000** Rows per CSV uploaded to a Custom Dashboard The Elite-tier Custom Dashboards CSV ingestion caps at 500,000 rows per dataset[5](https://flitstack.ai/migrations/hrms/bamboohr#source-5). Employee imports through the standard Import Tool are smaller in practice — a 5,000-employee load is large for the wizard.

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[11](https://flitstack.ai/migrations/hrms/bamboohr#source-11). 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.

## Pre-migration prep — the work before you touch BambooHR

*What must be true on the source, the destination, and across the team before the first row hits the Import Tool.*

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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4), 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.
>
> BambooHR Partner Import Tool Training

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[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8). 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[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8) [9](https://flitstack.ai/migrations/hrms/bamboohr#source-9).
- 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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4).
- 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[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8).
- 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[12](https://flitstack.ai/migrations/hrms/bamboohr#source-12).
- 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[13](https://flitstack.ai/migrations/hrms/bamboohr#source-13). 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.

## Import mechanisms: UI wizard, CSV, and programmatic loads

*Multiple paths in, each with different limits and shapes. Picking the wrong one is how mid-migrations stall at scale.*

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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4). 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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4). The Hours Importer and Custom Dashboards each have their own dedicated upload flows[14](https://flitstack.ai/migrations/hrms/bamboohr#source-14) [5](https://flitstack.ai/migrations/hrms/bamboohr#source-5).

Two operational constraints define how teams actually use it. First, there is no undo — every BambooHR training begins with a single-row test import[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4) [6](https://flitstack.ai/migrations/hrms/bamboohr#source-6). 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[9](https://flitstack.ai/migrations/hrms/bamboohr#source-9) [7](https://flitstack.ai/migrations/hrms/bamboohr#source-7). Official PHP and Python client libraries ship from BambooHR with fluent client builders and typed models[16](https://flitstack.ai/migrations/hrms/bamboohr#source-16). 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[18](https://flitstack.ai/migrations/hrms/bamboohr#source-18).

**20 MB** Per-file size cap on employee document uploads Employee file uploads reject files larger than 20 MB and return an error[19](https://flitstack.ai/migrations/hrms/bamboohr#source-19). Combined with the 1 GB per-employee storage allowance, this caps any individual signed PDF or scanned passport you can attach to a profile.

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[20](https://flitstack.ai/migrations/hrms/bamboohr#source-20). Deletions return a conflict response if the row has pending approval changes or is tied to an active pay schedule[20](https://flitstack.ai/migrations/hrms/bamboohr#source-20) — 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.

Under 500 employees on standard fields → native Import Tool. 500–5,000 with history → Import Tool for employees + programmatic loads for effective-dated tables. Over 5,000, complex history, or any re-runnable load → programmatic loads with the official PHP or Python client library.

## Mapping your data into BambooHR

*The longest section — because field mapping is where almost every migration that fails actually breaks.*

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

| Source                               | Destination                     | Note                                                                                                                                              |
| ------------------------------------ | ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| employee\_id / payroll\_id           | Employee # (custom or default)  | Flag this column as the unique identifier during import mapping                                                                                   |
| first\_name / last\_name             | firstName / lastName            | Preferred name maps to preferredName separately                                                                                                   |
| work\_email                          | workEmail                       | Used as the SSO match key in most Okta / Entra setups                                                                                             |
| date\_of\_birth                      | dateOfBirth                     | yyyy-mm-dd format; drives age and birthday fields[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8)                                      |
| gender                               | gender                          | Single-select list — pre-create options if you carry non-binary or X categories                                                                   |
| ethnicity / EEO category             | ethnicity, eeo (job category)   | US EEO-1 compliance fields — must match BambooHR's option set verbatim                                                                            |
| veteran\_status / disability\_status | veteranStatus, disabilityStatus | VEVRAA / Section 503 compliance — separate single-select lists                                                                                    |
| supervisor / manager                 | Supervisor (Reports To)         | Use Supervisor Email or Supervisor ID, not name — name matching breaks on duplicates[10](https://flitstack.ai/migrations/hrms/bamboohr#source-10) |
| hire\_date / termination\_date       | hireDate, terminationDate       | Drives tenure calculations and ACA status — load both even for active employees                                                                   |

### 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[26](https://flitstack.ai/migrations/hrms/bamboohr#source-26). 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[27](https://flitstack.ai/migrations/hrms/bamboohr#source-27).

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.

| Source                         | Destination                                     | Note                                                                            |
| ------------------------------ | ----------------------------------------------- | ------------------------------------------------------------------------------- |
| promotion / title-change event | jobInfo row                                     | One row per change with effectiveDate, jobTitle, department, supervisor         |
| raise / merit increase         | compensation row                                | Effective date, rate, payType, paySchedule, changeReason                        |
| leave start / return           | employmentStatus row                            | Two rows: one dated leave-start (Leave), one dated return (Active)              |
| termination                    | employmentStatus row + employee.terminationDate | Set status to Terminated on the term date; populate terminationDate on the root |

By default programmatic reads return only currently effective values; pass `onlyCurrent=false` on the employee read to include future-dated and historical values[7](https://flitstack.ai/migrations/hrms/bamboohr#source-7). 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[28](https://flitstack.ai/migrations/hrms/bamboohr#source-28). 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[11](https://flitstack.ai/migrations/hrms/bamboohr#source-11). 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[29](https://flitstack.ai/migrations/hrms/bamboohr#source-29) [30](https://flitstack.ai/migrations/hrms/bamboohr#source-30). 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[31](https://flitstack.ai/migrations/hrms/bamboohr#source-31). 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[19](https://flitstack.ai/migrations/hrms/bamboohr#source-19).

Hard limits to plan around: individual files cap at 20 MB on upload[19](https://flitstack.ai/migrations/hrms/bamboohr#source-19), 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[10](https://flitstack.ai/migrations/hrms/bamboohr#source-10). 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[10](https://flitstack.ai/migrations/hrms/bamboohr#source-10).

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[7](https://flitstack.ai/migrations/hrms/bamboohr#source-7). 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[11](https://flitstack.ai/migrations/hrms/bamboohr#source-11).

## The pitfalls that derail BambooHR migrations

*Eight specific failure modes — ranked by impact, each tied to the exact BambooHR mechanism that breaks.*

**high Import Tool has no undo button**

Every BambooHR Import Tool training opens with the explicit warning that the tool has no undo. A 5,000-employee import with a malformed Supervisor column or a misnamed Department list value cannot be rolled back via a single click — the only recourse is bulk-deletion of the imported employees (which orphans any time-off requests, files or goals already created) or a row-by-row corrective re-import. Run a single-employee test through the tutorial sandbox first, then a 10-row pilot, then the full file[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4) [6](https://flitstack.ai/migrations/hrms/bamboohr#source-6).

**high Single current row collapses effective-dated history**

Job Info, Compensation and Employment Status are effective-dated tables — BambooHR shows the most recent dated row as the current value and preserves prior rows as history[7](https://flitstack.ai/migrations/hrms/bamboohr#source-7). A migration that loads only the current job title and current pay rate erases every promotion, raise and leave-of-absence event from the timeline. Manager reports filtered by tenure or pay-change date will return empty. Build the import file with one row per historical change, dated correctly, and accept the row-count expansion this implies.

**high List-field values rejected when not pre-defined**

Single-select list fields — Department, Division, Location, Employment Status, EEO categories, custom dropdowns — store values from a fixed option set. The Import Tool will not silently create a new option when it encounters a value it doesn't recognise; the row is rejected and you spend the afternoon spotting which 18 rows had a typo or a casing mismatch[8](https://flitstack.ai/migrations/hrms/bamboohr#source-8) [9](https://flitstack.ai/migrations/hrms/bamboohr#source-9). Pre-create every list value through Customize before the import runs, and lowercase-trim the source export against the destination option set.

**high Supervisor field resolved by name fails on duplicates**

The Supervisor (Reports To) field is the only thing that builds the org chart, and the default name-based match breaks the moment two employees share a name. Culture Amp's BambooHR sync guide is explicit: hierarchy cannot be built reliably using Manager Names — you need Supervisor Email or a calculated Supervisor ID field, and every employee except the top leader must have a manager assigned[10](https://flitstack.ai/migrations/hrms/bamboohr#source-10). Switch the source export to email-based supervisor references before the first import touches a real account.

**high Access Levels not pre-built leaves managers blind**

Access Levels — Account Owner, Full Admin, HR Admin, Manager, Employee, plus Custom — control which fields and tables each user sees and edits. Import a manager into BambooHR before their Custom Access Level exists and they land at the default Employee level with no visibility into their team's compensation or performance, even though they own the org chart[11](https://flitstack.ai/migrations/hrms/bamboohr#source-11). Build Custom Access Levels before users get accounts, and grant them in the import file via the Access Level column or a follow-up bulk assignment.

**medium PTO balances loaded as snapshots, not historical accrual**

Time Off balances are imported as starting-line adjustments on the import date — they are not retroactive accruals, and they do not back-fill a request history. If HR expects to see "used 5 days in March, accrued 1.25 days in April" on day one, they will be disappointed: the platform shows only the current balance forward from the import[26](https://flitstack.ai/migrations/hrms/bamboohr#source-26) [27](https://flitstack.ai/migrations/hrms/bamboohr#source-27). Freeze accruals in the source on the cutover date, import balances same-day, and accept that the request log starts fresh on go-live.

**medium File upload capped at 20 MB and 1 GB per employee**

Employee file uploads reject files over 20 MB and the per-employee storage allowance is 1 GB[19](https://flitstack.ai/migrations/hrms/bamboohr#source-19). Teams migrating 15 years of scanned HR files — old performance reviews as multi-page PDFs, immigration paperwork, signed handbooks — hit the per-employee cap before they finish a single profile. The fix is to deep-link to S3 / Google Drive for the long-tail archive and only inline-upload the most recent or most-referenced documents on each profile.

**medium Payroll and benefits are US-only add-ons, not core**

BambooHR Payroll is a separately priced add-on, available only for US-based companies, and BambooHR Benefits Administration is similarly bolted on rather than part of the core HRIS. A migration scoped against "BambooHR" that quietly assumed payroll history would land in the same product runs into a per-pay-stub historical-payroll import that only exists once the Payroll add-on is contracted, and even then only for US payroll. Global teams will keep payroll in Gusto, ADP, Paylocity or a local provider integrated separately.

**low Okta provisioning cannot create new BambooHR employees**

The Okta integration for BambooHR is explicit about a one-way direction: you cannot create new users in BambooHR from Okta — assigning an Okta user to BambooHR with provisioning enabled returns an error, and the documented workaround is to import existing users from BambooHR first[33](https://flitstack.ai/migrations/hrms/bamboohr#source-33). Plan SSO provisioning as a post-migration step: load employees through the Import Tool or a programmatic load, then enable Okta or Entra ID provisioning for ongoing identity sync after go-live.

## Validation and cutover

*What to verify after the import job, in what order — and how to fail safely when something is wrong.*

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[19](https://flitstack.ai/migrations/hrms/bamboohr#source-19).
- 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[4](https://flitstack.ai/migrations/hrms/bamboohr#source-4) [6](https://flitstack.ai/migrations/hrms/bamboohr#source-6), 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[20](https://flitstack.ai/migrations/hrms/bamboohr#source-20).

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.

## Migration partners and tools

*Implementation specialists, iPaaS vendors, in-house onboarding — what each is good for and how to choose.*

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 →]\(/contact)

In this guide

## BambooHR migration checklist

An eight-phase, task-by-task punch list for moving employees, PTO balances, comp history, performance data, documents, and org structure into BambooHR. Typical timeline: 6–16 weeks.

0\. Decide & Plan 9 tasks

- **Document the list of in-scope BambooHR modules.** Decide which of core HR, Hiring (ATS), Onboarding, Time Off, Time Tracking, Performance Management, Benefits Administration, and Payroll are part of this project. Record each as in or out of scope.*If skipped: Mid-project scope additions force re-running mapping, sandbox tests, and access-level design from the start.*
- **Define historical-data scope per object.** Decide how many years of Job Info, Compensation, Employment Status, Time Off ledger entries, performance assessments, and uploaded documents move across. Record cut-off dates per object.*If skipped: Without an explicit cut-off, the export expands into a multi-year dump that no one budgeted for transforming.*
- **Confirm BambooHR Payroll suitability for your geography.** BambooHR Payroll runs US-only. If you have non-US employees, confirm that they will sit in BambooHR for core HR while payroll runs in a separate system, and document the boundary.*If skipped: Discovering the US-only payroll constraint after employees are loaded forces a parallel payroll project under time pressure.*
- **Pick the BambooHR plan (Core or Pro) and confirm required add-ons.** Performance Management, Benefits Administration, Time Tracking, Hiring, and Payroll are separately priced. Confirm which the project will purchase before designing field schemas.*If skipped: Mapping work targeted at a module that is later cut wastes weeks of transform engineering.*
- **Assign a single accountable migration owner (DRI).** Name one person responsible for go/no-go on cutover. Document an escalation chain that includes HR, Payroll, IT, and Finance representatives.
- **Capture GDPR, residency, and retention obligations.** BambooHR is a US-hosted SOC 2 Type II processor. If you process EU employee data, document the Data Processing Agreement, transfer-impact assessment, and the retention rules that change on cutover.*If skipped: Legal blocks the import on go-live day when residency or DPA review was not completed earlier.*
- **Set the cutover date, source freeze window, and parallel-run window.** Choose a date that avoids payroll close, open-enrollment, and performance-review windows. Define the freeze window during which the source HR system goes read-only.*If skipped: A cutover during payroll close forces a partial cutover and a hand-reconciled pay run.*
- **Document the migration success criteria in writing.** List the row counts, balance reconciliations, and user-acceptance checks that must pass before the project is closed. Include the source-system decommission date.
- **List explicitly out-of-scope items.** Examples: legacy survey results, deactivated user logins, training-platform completions, fitness-benefit balances. Capture them so they do not silently re-enter scope mid-project.

1\. Pre-Migration Prep 21 tasks

- **Run dedup on source employee records using work email + national ID.** Resolve duplicates in the source before export so two profiles do not land as one employee in BambooHR.*If skipped: Duplicate source rows merge into a single employee record and historical compensation rows attach to the wrong person.*
- **Standardize work email casing and trim whitespace.** Lowercase the email and remove trailing spaces. BambooHR uses work email as the primary user identifier.
- **Standardize phone numbers to E.164 format.** Strip parentheses, spaces, and dashes; prefix the country code with a leading plus.
- **Standardize country names to the BambooHR country list.** BambooHR rejects country values that do not match its built-in list. Replace abbreviations such as USA, U.S., and US with United States.*If skipped: Country-field rejections halt the import row-by-row instead of failing the file once at the top.*
- **Resolve employees with missing required fields.** BambooHR requires first name, last name, and hire date at minimum. Fix missing values in the source rather than padding them with placeholder data later.
- **Export baseline record counts per object.** Record counts for active employees, terminated employees, dependents, contacts, time-off categories, documents, and goals. These become the Phase 6 reconciliation reference.*If skipped: Without a count baseline you cannot prove later whether a number mismatch is a migration loss or a source-side change.*
- **Inventory all custom employee fields in the source.** Capture field name, type, picklist values, required-on-import flag, and example values. This becomes the master mapping reference for Phase 3.
- **Provision the BambooHR production tenant and confirm subdomain.** Confirm that the {companyDomain}.bamboohr.com URL matches what you will hand to integrations and SSO.
- **Request a sandbox or test account from BambooHR.** Use the test account for Phase 4 dry runs. Keep configuration in lockstep with production so sandbox results extrapolate.*If skipped: Skipping a sandbox means production becomes the test environment, and the Import Tool has no undo.*
- **Configure company-level settings: legal entity, EIN, time zone, work week, and default currency.** These settings change how dates, time-off accruals, and pay rates are interpreted at import time.*If skipped: A wrong company time zone shifts every imported datetime by hours and corrupts PTO accrual day boundaries.*
- **Add and configure list-field values via Customize → Tabs/Fields.** Pre-create every Department, Division, Location, Employment Status, Pay Schedule, EEO Job Category, and Job Title value that the source data references.*If skipped: Importing a value that is not in the BambooHR list silently drops the field, leaving employees with blank departments and bad reports.*
- **Create all custom fields before any import.** Add custom single-value fields and Custom Tables (Education, Certifications, Licenses, and any new ones) via Settings → Customize → Tabs/Fields. Match the source data types from the audit.*If skipped: Importing into a field that does not exist yet drops the data on the row with no error indication.*
- **Build the Access Levels matrix.** Decide who is Account Owner, Full Admin, HR Admin, Manager, Employee, or a Custom access level. Map the source role list to these six roles.
- **Create Time Off categories and policies.** Define each category (Vacation, Sick, Bereavement, Parental, etc.), accrual rule, carryover rule, and which employees the policy applies to.*If skipped: Loading balance adjustments before a policy exists strands the balance with nowhere to attach.*
- **Build the holiday calendars per country and location.** Add fixed and floating holidays before loading time-off balances so accrual math lands on the correct working days.
- **Create Employee File categories and folder structure.** Confirm folders such as Tax Documents, Signed Offer Letters, Performance Reviews, and Disciplinary Records exist before bulk document upload.
- **Pre-create integrations in a paused state.** Set up Slack, Microsoft Teams, calendar sync, Okta provisioning, ATS push-back, and Payroll integrations but disable them until cutover.*If skipped: Active notification workflows fire during bulk import and spam employees with onboarding notifications for back-dated hires.*
- **Communicate the source-system freeze window to all users.** Send the freeze date and time in advance and post it where HR Admins and managers will see it.*If skipped: Source-system changes after the freeze produce a delta the cutover plan cannot reconcile cleanly.*
- **Schedule role-based training before go-live.** Sessions for employees (self-service), managers (approvals, reports), and HR Admins (full UI). Use BambooHR's interactive guides as the baseline.
- **Designate first-responders for the first 14 days post-cutover.** Pick two HR Admins and one IT contact who will triage employee questions and data fixes in BambooHR.
- **Distribute the new BambooHR login URL and password-reset path.** Confirm employees know where to log in and how to recover access on day one.

2\. Source Export 14 tasks

- **Export the master employee list to CSV with all standard and custom fields.** Include first name, last name, work email, hire date, employment status, department, division, location, manager, pay rate, pay schedule, EEO category, and every custom field from the Phase 1 audit.
- **Export Job Info history per employee.** Export every effective-dated row that changed Job Title, Department, Division, Location, Manager, or Reports To. Keep the original effective date on each row.*If skipped: Collapsing history into a current snapshot loses the audit trail that the BambooHR Job Info table is designed to preserve.*
- **Export Compensation history per employee.** Export salary, hourly rate, currency, pay schedule, and effective date for each compensation change. Include bonus history with date, amount, and reason.*If skipped: Loading only a current pay rate loses the comp ladder used by retention analysis and pay-equity reviews.*
- **Export Employment Status history per employee.** Include Active, Leave, Terminated, Contractor, and any custom statuses with the date each became effective.
- **Export US demographic fields where collected.** Gender, ethnicity, EEO Job Category, veteran status, and disability status. Export each into a column with the source picklist value preserved.
- **Export Time Off balances and ledger entries as of the freeze date.** Per employee, per policy, export current balance, year-to-date accrued, year-to-date taken, and the full ledger of accrual and usage transactions.*If skipped: Without a ledger you can only restore today's balance, not the audit trail needed for legal and payroll disputes.*
- **Export approved and pending time-off requests.** Export request id, employee, policy, start date, end date, hours, status, and approver for each in-flight request.
- **Export Performance Management data.** Export goals, self-assessments, manager assessments, peer feedback, and 360-degree review responses with their original timestamps.
- **Export the org chart as a Reports-To list.** BambooHR builds the org chart from the Supervisor field on each employee. Export one row per employee with employee email and supervisor email.*If skipped: A manager who is missing from the file or whose email is misspelled breaks the entire branch below them in the org chart.*
- **Export Department, Division, and Location lookup tables.** Pull the raw list of values so the Phase 3 mapping spreadsheet can resolve mismatches against the BambooHR-side list.
- **Export the user list and access roles.** Capture which users had admin, manager, payroll-admin, or read-only access in the source so Phase 1 access-level decisions stay grounded in reality.
- **Export employee documents and their metadata.** Pull binaries (PDF, DOCX, PNG, JPG) and a metadata file with employee email, document category, original filename, and upload date.*If skipped: Without metadata you have a folder of files no one can re-attach to the right employee.*
- **Capture screenshots and configuration exports of source-system automations.** Onboarding workflows, offboarding checklists, time-off auto-approvals, and notification rules will be rebuilt by hand in BambooHR.
- **Record the exact timestamp of each export.** Log the date and time per export file. The delta between this timestamp and cutover is what you re-export on cutover day.

3\. Transform & Map 26 tasks

- **Build a field-by-field mapping spreadsheet per object.** Columns: source field, source type, BambooHR field name (from the Field Names reference), BambooHR type, transformation rule, required-on-import flag, sample value, mapping owner.*If skipped: Without one source of truth, two engineers map the same field two different ways and the discrepancy surfaces only at validation.*
- **Resolve picklist-value mismatches against BambooHR list fields.** Examples: source 'F/T' → 'Full-Time'; source 'Terminated-Voluntary' → 'Terminated'. Document every replacement so it can be re-applied on cutover day.*If skipped: A picklist value that does not exist in BambooHR drops the field on that row with no error marker.*
- **Choose the upsert key per object.** Work email is the practical key for employees. For Job Info, Compensation, and Employment Status table rows, use the BambooHR-issued row id once created.
- **Decide handling for source fields with no BambooHR equivalent.** Per field: drop, concatenate into the Notes section, or create a new custom field. Record the decision in the mapping spreadsheet.
- **Convert all dates to YYYY-MM-DD.** BambooHR's date type is yyyy-mm-dd. Reject anything not in that format before upload.*If skipped: MM/DD vs DD/MM ambiguity silently swaps day and month on every row.*
- **Normalize currency values to plain decimals with a period separator.** Strip thousands separators and currency symbols. For non-default currencies, structure the value as {value, currency} with an ISO-4217 code (e.g. EUR).
- **Encode all text files as UTF-8 without a byte-order mark.** Re-save every CSV in UTF-8. Special characters in non-Latin names break parsing if the file is in Windows-1252 or ISO-8859-1.*If skipped: Mis-encoded files corrupt accented characters on import and force a name fix per employee after the fact.*
- **Escape commas, quotes, and newlines inside text fields.** Wrap any field that contains a comma, double quote, or newline in double quotes and double the inner double quotes per RFC 4180.
- **Truncate text fields that exceed BambooHR's column length.** Confirm each text-field length cap against the destination schema and decide truncation vs. moving overflow into Notes.
- **Validate boolean and checkbox values.** BambooHR accepts 'true'/'false' for bool and 'yes'/'no'/'checkbox' for checkbox fields. Map any other source representation to these.
- **Validate phone numbers against the phone field type.** Confirm digits, plus signs, and approved separators only. Reject extensions in unsupported formats and either drop or move to a custom field.
- **Decide the strategy for original record-created timestamps.** BambooHR does not let you override created-at on the employee record directly. Either re-stamp to cutover date or preserve the original via a custom date field labeled 'Source Created'.*If skipped: Field history starts on cutover day with no way to back-fill, surprising auditors and tenure reports.*
- **Decide the strategy for inactive / terminated employees.** Choose between importing terminated employees as inactive in BambooHR for tenure history vs. archiving them outside the platform and loading only active staff.
- **Confirm the Account Owner used for the bulk import.** Use a dedicated 'Data Migration' Account Owner so audit logs cleanly attribute the bulk changes to the migration project.
- **Shape employee records with US demographic columns.** Map gender, ethnicity, EEO Job Category, veteran status, and disability status into their corresponding BambooHR fields. Confirm every source value resolves to a list value that exists on the destination side.*If skipped: An EEO Job Category that does not match the destination list leaves the field blank and breaks EEO-1 reporting at year-end.*
- **Compute Time Off balances as of cutover and build the per-policy Adjust Balance file.** For each employee and each policy: current balance, units (hours or days), and the adjustment reason 'Migration opening balance'. Confirm the per-policy holiday calendar and carryover rule before computing.*If skipped: A wrong opening balance shows up the first day employees log in and erodes confidence in the system within 24 hours.*
- **Pre-stage holiday calendars and verify accrual schedules.** Per location, list which holidays accrue, which prorate, and which days the accrual engine will treat as working days post-cutover.
- **Re-shape Job Info history as a row-per-change file for the Job Info table.** Each row carries employee id, effective date, job title, department, division, location, and reports-to. Sort ascending by effective date per employee so the history loads in the right order.*If skipped: Out-of-order effective dates load the history backwards and the most-recent row no longer reflects today's role.*
- **Re-shape Compensation history as a row-per-change file for the Compensation table.** Columns: employee id, effective date, pay rate, pay-rate type (hourly/salary/contract), pay per, pay schedule, change reason. Treat bonuses and one-time payouts separately under the Bonus table.*If skipped: Loading compensation as a single current row erases the comp ladder used for retention and pay-equity analysis.*
- **Re-shape Employment Status history as a row-per-change file.** Columns: employee id, effective date, status (Active, Leave, Terminated, Contractor), comment. Use this table to drive ACA Status Category, which BambooHR derives automatically.
- **Re-shape performance data per BambooHR's Performance Management module.** Map goals to the Goals object, self/manager assessments to assessments, and 360 responses to peer assessments. Preserve original due dates and completion dates as custom date fields where the platform cannot back-date.*If skipped: Re-stamping performance data to cutover day collapses years of review history into a single date.*
- **Plan the org chart load via the Supervisor (Reports To) field.** Load employees in two passes: first without supervisors, then with supervisors. Leave the CEO's Reports To blank to anchor the top of the chart. Use employee email or BambooHR id for the Reports-To match.*If skipped: Loading employees and supervisors in one pass fails wherever a supervisor has not been created yet, leaving employees with broken reporting lines.*
- **Reshape Custom Tables data (Education, Certifications, Licenses, custom multi-row).** Build one CSV per table with stable employee id keys, one row per record.
- **Prepare the document upload manifest with file size and category checks.** Confirm every file is under the 20 MB per-file cap and each employee's total stays under the 1 GB per-employee cap. Group files by destination category id.*If skipped: Files over the per-file or per-employee cap silently fail to upload and the metadata-linkage check fails at validation.*
- **Convert unsupported attachment file types where needed.** Convert legacy formats to PDF, DOCX, XLS, PNG, or JPG. Performance Goal attachments accept PDF, XLS, and DOCX only.
- **Decide the field-level permissions strategy per custom field.** Per field, decide who can view and edit: Account Owner, Full Admin, HR Admin, Manager, or Employee. Set this in the destination before import so values are not visible to the wrong audience on day one.

4\. Sandbox Test Migration 13 tasks

- **Load a 5–10 employee sample via the BambooHR Import Tool.** Pick a sample that covers active, terminated, on-leave, contractor, and international employees so edge cases surface early.*If skipped: A sample of only US active employees hides the bugs that hit the harder cases in production.*
- **Walk through the Import Tool tutorial before the first sandbox load.** The Import Tool has no undo. Confirm the operator has watched the training and run the interactive guide at least once.*If skipped: An accidental destructive import in production requires a manual revert that takes longer than the original load.*
- **Validate 5–10 random sandbox employees field by field.** Compare each value side-by-side against the source. Note dates, currency, country, and custom-field mismatches.
- **Test edge cases: names with non-ASCII characters, multi-line addresses, leading zeros in IDs.** Confirm BambooHR's importer round-trips the special characters and preserves leading zeros on text-typed numeric fields.
- **Test the two-pass org-chart load.** Load employees first without supervisors, then back-fill the Reports To field. Confirm the org chart renders without orphan branches.
- **Load a sample Job Info, Compensation, and Employment Status history.** Confirm the effective-dated rows display in chronological order on the employee profile.*If skipped: Effective-date sort issues only show up in the UI, which masks the problem until UAT.*
- **Load a sample of opening Time Off balances via Adjust Balance.** Confirm the adjustment displays in the employee's ledger with the migration reason and that the future-balance calculator extrapolates correctly.
- **Upload sample documents to confirm size and category routing.** Confirm files arrive in the correct Employee File category and that the 20 MB cap blocks oversize files cleanly.
- **Load a sample of Performance goals and assessments.** Confirm goal status, due date, and any attached files render correctly in the employee profile.
- **Run a full-volume dry run in the sandbox.** Load the entire employee list plus historical tables and time the run. Multiply by a safety factor to forecast cutover-window duration.*If skipped: A cutover window that turns out to be too short forces a partial go-live with employees split between systems.*
- **Capture every error code and row id from the sandbox import logs.** Categorize errors as recoverable (fix the transform) vs. non-recoverable (drop the row, document the reason).
- **Have an HR domain expert review 25 sandbox employees.** Pick an HR Admin who does not work on the migration. Their job: spot anything that 'looks wrong' to a daily user.
- **Get written sign-off on sandbox results before cutover scheduling.** The DRI signs off on row counts, balance reconciliations, and the sandbox UAT report.*If skipped: Skipping sign-off lets the cutover proceed with known sandbox defects still unresolved.*

5\. Production Cutover 13 tasks

- **Confirm the source-system freeze is in effect.** Verify there are no employee, time-off, or compensation changes in the source in the hour before export.*If skipped: Late source-side edits create a delta that the cutover plan has no time to reconcile.*
- **Take a final full export of source data.** Re-run every export from Phase 2 at the freeze time so the import file reflects the exact state at cutover.
- **Disable BambooHR integrations and notification workflows.** Pause Slack, Microsoft Teams, Okta provisioning, calendar sync, payroll push, and onboarding workflows for the duration of the import.*If skipped: Active integrations fire during the bulk load, sending hundreds of welcome emails for back-dated hires.*
- **Load Access Levels and Custom Access Levels first.** Create the role tiers before employees, then assign employees to roles as part of the employee load.
- **Load active employees first via the Import Tool, supervisors blank.** First-pass file: every active employee without their Reports To field set. Use the upsert key chosen in Phase 3.
- **Load terminated employees and contractors next.** Run a separate file that imports inactive employees with employment status pre-set, so they do not appear in active rosters.
- **Back-fill the Reports To field in a second pass.** Update each employee's Supervisor field via the Import Tool now that every supervisor exists.*If skipped: A typo in the supervisor email field on first pass leaves the org chart broken and routes manager-only reports to the wrong people.*
- **Load Job Info, Compensation, and Employment Status history.** Load one row per effective-dated change. Capture the resulting row id for each insert.
- **Load Custom Tables: Education, Certifications, Licenses, and any custom multi-row tables.** One CSV per table, keyed by employee id.
- **Load Time Off categories, policies, and opening balances.** Confirm categories and policies exist; then use Adjust Balance per employee to set opening balances as of cutover. Tag every adjustment with the migration reason.
- **Upload employee documents in batches by category.** Confirm each file is under 20 MB and each employee's total stays under 1 GB.
- **Capture row counts, error logs, and job ids for every load step.** Save the Import Tool history and the load job ids in the migration runbook for audit and rollback evidence.*If skipped: Without per-step evidence a partial failure has no recovery point and the team starts the load over from row one.*
- **Re-enable BambooHR integrations and notification workflows.** Resume Slack, Microsoft Teams, Okta provisioning, payroll, and onboarding integrations only after every load step is reconciled.

6\. Validate 14 tasks

- **Reconcile total active employee count between source and BambooHR.** Pull the Active employee count via List Employees or a custom report. The number must match the Phase 1 baseline minus any agreed exclusions.*If skipped: An unexplained delta of even a handful of employees signals a silent drop somewhere in the transform.*
- **Reconcile terminated employee count.** Confirm every terminated source employee landed as inactive in BambooHR (or was excluded per Phase 3).
- **Reconcile total annualized payroll across active employees.** Aggregate the current pay rate times pay frequency for every active employee and compare to the source figure.*If skipped: A wrong pay-rate type (hourly vs. salary) on a batch of employees inflates or deflates the total by a factor of 2,000.*
- **Reconcile Time Off opening balances per policy per employee.** Confirm BambooHR balance equals the Phase 3 computed balance to within one decimal place. Investigate every mismatch.*If skipped: Off-by-one balance errors generate dozens of HR tickets in the first week and erode trust in the new system.*
- **Cross-check 30 random employees field by field against the source.** Pick employees at random across departments, statuses, and tenures. Walk every field on each profile and confirm parity.
- **Verify the org chart renders without orphan branches.** Open the BambooHR org chart and confirm every employee has the correct supervisor and that the CEO sits alone at the top.
- **Sample 20 Job Info history rows for ordering and date accuracy.** Confirm rows display in chronological order and that effective dates were not silently re-stamped to cutover.
- **Sample 20 Compensation history rows for amount, currency, and date accuracy.** Confirm currency tagging carried across for non-default-currency rows and that bonus rows landed in the Bonus table, not Compensation.
- **Spot-check 15 employees' uploaded documents for category, filename, and access.** Open each document, confirm it renders, and confirm the right access levels can see it.
- **Verify Performance goals, assessments, and 360 records attached to the right employees.** Sample 10 employees and confirm their goal history and assessment responses match the source.
- **Run a SOC 2 / GDPR evidence collection pass.** Capture the import job ids, who ran them, and when. File alongside the DPA and transfer-impact assessment captured in Phase 0.
- **Have 3–5 power users complete their day-one workflows in BambooHR.** Cover request time off, approve time off, look up an employee, run a custom report, and run the directory.*If skipped: Workflow gaps surface only at this layer and are cheaper to fix before go-live than after.*
- **Document every UAT-surfaced data issue and assign an owner.** Triage as block-go-live vs. fix-post-cutover. Block-go-live items go back into the cutover runbook for re-load.
- **Get written sign-off from the migration sponsor before Phase 7.** Sponsor signs off on row-count reconciliation, balance reconciliation, and the UAT report.

7\. Post-Migration Cleanup 12 tasks

- **Announce go-live to all employees with login URL and help contact.** Include the BambooHR mobile-app download links (iOS and Android) and a short FAQ for password reset and time-off requests.
- **Run role-based training sessions.** Employee self-service (15 minutes), manager workflows (30 minutes), HR Admin deep dive (60 minutes). Record each session for new hires.
- **Set the source HR system to read-only.** Disable writes per the freeze-window plan. Communicate the read-only date to the team that still references historical data.
- **Rebuild source-system reports inside BambooHR.** Custom reports and dashboards do not transfer. List the top 10 reports the team relied on and rebuild each via BambooHR's reporting UI.*If skipped: Without rebuilt reports the HR team falls back to the source system within a week, undermining cutover.*
- **Rebuild onboarding and offboarding workflows.** Convert the source-system checklists into BambooHR Onboarding tasks and offboarding tasks. Map approvers and notification routing.
- **Re-establish Slack, Microsoft Teams, calendar, and SSO integrations.** Confirm Okta provisioning works for new hires before disabling the manual create step.
- **Connect ATS, Payroll, Benefits Administration, and Time Tracking add-ons.** If purchased in Phase 0, configure each add-on after the core HR data is stable. Run a dry pay calc before the first real run.*If skipped: A first real payroll run on uncorroborated data is the most expensive way to find an import defect.*
- **Schedule a 30-day post-migration retrospective.** Capture what went well, what surprised the team, and which Phase 3 transform rules need updating for any future re-runs.
- **Set the source-system decommission date.** Typically 90 days after cutover, after the final retention window has closed. Document who signs off on shutdown.
- **Archive source-system exports and the migration runbook to long-term storage.** Encrypt the archive, store the key separately, and record retention duration per compliance policy.
- **Update the access-level matrix and remove the dedicated migration Account Owner.** Lower the migration user's role to read-only or deactivate it once the audit trail is captured.
- **Close the migration project formally.** Final status report, lessons learned, and a project-closure note distributed to stakeholders.

Questions, answered

## Migrating to BambooHR: questions

How long does migration to BambooHR take?

A spreadsheet-to-BambooHR migration of under 100 employees runs two to four weeks end-to-end inside the BambooHR onboarding service. A 500-to-2,000-employee project with multi-year compensation history, Custom Tables, document migration and Performance Management add-on runs two to three months including preparation, dry runs, validation, training and a 48-hour hyper-care window.

Can I migrate from ADP Workforce Now to BambooHR?

Yes — ADP Workforce Now is one of the most common BambooHR migration sources. Standard employee fields map cleanly, but ADP's payroll history will not move into BambooHR unless you contract the US-only BambooHR Payroll add-on. Plan effective-dated history reconstruction and ADP user-ID to BambooHR Supervisor-email mapping.

Can I migrate from Paychex Flex or Zenefits to BambooHR?

Yes, and spreadsheet-shaped exports from Paychex Flex or Zenefits are usually the cleanest migration paths because the source data is already flat. Watch list-field casing on Department, Division and Employment Status, rebuild Time Off policies from scratch inside BambooHR, and load Compensation history as effective-dated rows rather than a single current row.

Does BambooHR preserve original hire dates and history on import?

Partially. Hire date, termination date and every dated row on Job Info, Compensation and Employment Status can be loaded with their original dates, and BambooHR preserves the timeline. System fields like createdDate are stamped on insert. Use custom Legacy Hire System and Legacy Employee ID fields to preserve the prior audit trail.

What's the difference between the BambooHR Import Tool and programmatic loads?

The Import Tool is a UI wizard that maps Excel or CSV files against existing BambooHR fields and is best for one-shot employee loads under a few thousand records with a visual mapping step. Programmatic loads with the official PHP and Python client libraries handle larger volumes, effective-dated table history, and repeatable, audit-logged loads.

Can I migrate Custom Tables to BambooHR?

Yes. Define Custom Tables — Education, Certifications, Licenses, Visa Information — under Settings, Customize before importing any rows. Custom Tables hold per-employee multi-row data, are loaded one row per record through the Import Tool or programmatically per table, and cannot be re-typed retroactively after data is loaded.

What happens to PTO balances during a BambooHR migration?

PTO balances are imported as starting-line adjustments on the import date, not retroactive accruals. Create Time Off categories and policies first, freeze accruals in the source on the cutover date, export current balances, and import them as adjustments. BambooHR accrues forward from that starting line using the policy you configured.

Is there an undo or rollback for BambooHR imports?

No native undo exists for the BambooHR Import Tool — every training opens with that warning. The practical fallback is to export everything to S3 before the import starts, stamp every imported employee with a Migration Batch ID custom field, and if catastrophe strikes, bulk-deactivate by that batch ID and re-import.

## Sources

1. [BambooHR — Wikipedia](https://en.wikipedia.org/wiki/BambooHR)
2. [Import Tool Training — BambooHR Partners](https://partners.bamboohr.com/reseller-training-resources/import-tool-training/)
3. [Custom Dashboards: Import CSV Data — BambooHR Product Updates](https://www.bamboohr.com/product-updates/custom-dashboards-import-csv-data)
4. [Importing Data into BambooHR — BambooHR Support](https://help.bamboohr.com/hc/en-us/articles/115004527547-Importing-Data-into-BambooHR)
5. [Get Employee — BambooHR Documentation](https://documentation.bamboohr.com/reference/get-employee)
6. [Field Types — BambooHR Documentation](https://documentation.bamboohr.com/docs/field-types)
7. [Add or Update Values for List Fields — BambooHR Documentation](https://documentation.bamboohr.com/reference/metadata-add-or-update-values-for-list-fields)
8. [Sync HRIS Data from BambooHR — Culture Amp Support](https://support.cultureamp.com/en/articles/7048549-sync-hris-data-from-bamboohr)
9. [Customize Your BambooHR Account — BambooHR Help Center](https://help.bamboohr.com/s/article/960685)
10. [BambooHR integration known issues — Okta Documentation](https://help.okta.com/en-us/content/topics/provisioning/bamboohr/bamboohr-known-issues.htm)
11. [How to Switch HR Software the Easy Way — BambooHR](https://www.bamboohr.com/resources/guides/easy-to-switch)
12. [Hours Importer Updates — BambooHR Product Updates](https://www.bamboohr.com/product-updates/hours-importer-updates)
13. [Official client libraries — BambooHR Documentation](https://documentation.bamboohr.com/docs/sdks)
14. [Programmatic load throughput guidance — BambooHR Documentation](https://documentation.bamboohr.com/docs)
15. [Upload Employee File — BambooHR Documentation](https://documentation.bamboohr.com/reference/upload-employee-file)
16. [Delete Employee Table Row — BambooHR Documentation](https://documentation.bamboohr.com/reference/delete-employee-table-row)
17. [PTO Tracking & Time Off Management Software — BambooHR](https://www.bamboohr.com/platform/time-and-attendance/time-off)
18. [Calculate Future Time Off Balances — BambooHR Help Center](https://help.bamboohr.com/s/article/587398)
19. [Field Names — BambooHR Documentation](https://documentation.bamboohr.com/docs/list-of-field-names)
20. [List Goals — BambooHR Documentation](https://documentation.bamboohr.com/reference/list-goals)
21. [Performance Management Systems for HR — BambooHR](https://www.bamboohr.com/platform/performance-management/)
22. [Employee Document Upload — BambooHR Help Center](https://help.bamboohr.com/s/article/640097)
23. [BambooHR integration known issues — Okta Documentation](https://help.okta.com/en-us/content/topics/provisioning/bamboohr/bamboohr-known-issues.htm)

Get a quote

## Moving to BambooHR?

Tell us where your data lives today and roughly how much there is. We scope the migration and the BambooHR setup with you, then send a quote.

[Get a quote](https://flitstack.ai/contact)
