> ## Documentation Index
> Fetch the complete documentation index at: https://beebole.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Legacy Migration — Import Your Old Data into Beebole

> Import your existing Beebole data — people, projects, time records, and settings — into the current platform with the one-time Legacy Migration tool.

The **Legacy Migration** tool lets you import data from a previous Beebole account into your new Beebole workspace. It is a one-time, guided process that preserves your historical time records, people, projects, tasks, activities, absence types, schedules, custom fields, and more.

<Info>
  The migration can only be performed once per account and is restricted to administrators. If migration has already been completed, the tool displays a confirmation message and prevents a second run.
</Info>

***

## What gets migrated

The migration imports the following data from your legacy account:

| Data type         | Notes                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------- |
| **People**        | Active and archived team members, including schedule assignments and billing/cost rates |
| **Companies**     | Top-level project containers, mapped to the new project category structure              |
| **Projects**      | Full project hierarchy including subprojects                                            |
| **Tasks**         | Task definitions, statuses, and category assignments                                    |
| **Activities**    | Job types (legacy activities) carried over as tasks                                     |
| **Groups**        | Reporting groups mapped to the new structure                                            |
| **Branches**      | Branch data migrated as tags                                                            |
| **Absence types** | Leave categories and quotas                                                             |
| **Schedules**     | Work schedule definitions and person assignments                                        |
| **Custom fields** | Field definitions and their values                                                      |
| **Time records**  | Historical time entries, including billability and project assignments                  |
| **External IDs**  | Preserved for any records that had external identifiers                                 |

<Tip>
  If you choose to include only active records, archived people and projects are skipped. Archived records referenced by time records are still created to maintain data integrity.
</Tip>

***

## Before you start

Before running the migration, confirm the following:

* You are an administrator of the new Beebole account.
* You have your **Legacy API Key** from your previous Beebole account. You can find it in your legacy account's API settings, or contact [support@beebole.com](mailto:support@beebole.com) if you are unsure where to look.
* You have decided whether to migrate all records or only active ones.
* You have decided how far back to import time records (or whether to import them at all).

***

## Running the migration

<Steps>
  <Step title="Open the migration tool">
    In your Beebole account, go to **Settings** > **Legacy Migration**.
  </Step>

  <Step title="Enter your Legacy API Key">
    Paste your **Legacy API Key** into the field provided. This key authenticates your request against your previous account and allows the migration tool to read your data.
  </Step>

  <Step title="Configure migration options">
    Set the following options before running the audit:

    * **Only active entities** — Enable this to skip archived people and projects. Leave it off to import everything, including archived records.
    * **Include time records from** — Choose a start date if you only want to bring over time entries from a certain point. Leave blank to import all historical data.
  </Step>

  <Step title="Run the audit">
    Click **Start Audit**. Beebole connects to your legacy account and counts everything that will be migrated — people, companies, projects, tasks, activities, absence types, schedules, custom fields, quotas, and time records. The audit does not modify any data.

    <Info>The audit may take a few seconds depending on your data volume.</Info>
  </Step>

  <Step title="Review the audit results and choose what to migrate">
    The **Audit Results** screen shows a breakdown of records found in your legacy account, with a live count per data type. Under **What to migrate** and **Data that links them**, untick anything you don't want to bring over — people, projects, tags, schedules, budgets, time records, the manager structure, and more are individually selectable. Review the counts and the time record date range before proceeding.
  </Step>

  <Step title="Start the migration">
    Click **Start Migration**. The migration runs in the background and a progress bar shows each phase as it completes.

    <Warning>Do not close or refresh the page while the migration is running. The process may take several minutes depending on your data volume.</Warning>
  </Step>

  <Step title="Review the migration report">
    When finished, Beebole displays a summary report showing how many records were created, skipped, or failed for each phase. If there are warnings or failures, review them and contact [support@beebole.com](mailto:support@beebole.com) if you need help resolving them.
  </Step>
</Steps>

***

## Migration phases

The migration runs through the following phases in order:

1. **Projects** — Creates project structure from legacy companies
2. **Activities** — Migrates job/activity types as tasks
3. **Absence Types** — Creates absence categories
4. **Schedules** — Imports work schedule definitions
5. **Groups** — Migrates reporting groups
6. **Branch Tags** — Converts branch data to tags
7. **People** — Creates team members
8. **Tag Assignments** — Links tags to records
9. **Team Members** — Assigns people to projects
10. **Project Assignments** — Applies exclusive project membership settings
11. **Schedule Assignments** — Links people to their work schedules
12. **Billing & Costs** — Imports billing and cost rates
13. **Custom Fields** — Creates custom field definitions
14. **Custom Field Values** — Attaches custom field data to records
15. **Absence Quotas** — Migrates leave quota balances
16. **External IDs** — Preserves any external system identifiers
17. **Time Records** — Imports historical time entries (if selected)
18. **Backfill** — Completes any cross-reference data
19. **Done** — Migration complete

***

## What to expect after migration

* All migrated data is immediately available in your Beebole account.
* People receive no automatic notifications — you can invite them manually from the **People** page in the sidebar when you are ready.
* Review your project categories and task statuses to ensure the structure meets your needs.
* Check a sample of time records in [Reports](/help/documentation/reports) to confirm data accuracy.

***

## Related content

<CardGroup cols={2}>
  <Card title="Account Settings" icon="gear" href="/help/documentation/account-settings">
    Manage your organization profile and account-level configuration.
  </Card>

  <Card title="Data Exports" icon="download" href="/help/documentation/data-exports">
    Export your Beebole data for backup or external analysis.
  </Card>
</CardGroup>

## Frequently asked questions

<AccordionGroup>
  <Accordion title="Can I run the migration more than once?">
    No. The migration is a one-time operation. Once it has been completed, the tool is locked and displays a confirmation message. If you need to re-migrate data, contact [support@beebole.com](mailto:support@beebole.com).
  </Accordion>

  <Accordion title="Can I migrate only part of my data?">
    Yes. You can choose to migrate only active records (skipping archived people and projects) and set a start date to limit how far back time records are imported. You can also choose not to include time records at all if you only need to bring over the account structure.
  </Accordion>

  <Accordion title="What happens if some records fail to migrate?">
    The migration completes even if individual records fail. The final report shows which phases had failures and how many records were affected. Most failures are caused by data inconsistencies in the legacy account. Review the warnings and contact support if you need help.
  </Accordion>

  <Accordion title="Will migrated people receive an invitation email?">
    No. Migrating people creates their records in Beebole but does not send invitation emails. You can invite them from the **People** page in the sidebar whenever you are ready for them to log in.
  </Accordion>

  <Accordion title="Can two accounts migrate at the same time?">
    No. The migration process runs one account at a time. If another account's migration is already in progress, you will see a message letting you know that Beebole will be ready for yours shortly.
  </Accordion>
</AccordionGroup>