# CRM migration

> Import your contacts, deals, cases and activity history from HubSpot, Pipedrive or Capsule.

Source: https://help.clockworkcrm.com/admin/crm-migration
Last updated: 2026-09-28

**Administrator Tools → CRM Migration** imports your data from HubSpot, Pipedrive or Capsule. Only
administrators can open it. Nothing is changed in the CRM you import from: Clockwork CRM only asks
for read access.

Migrations run in the background, so you can leave the page while one runs and come back to it.

## The migration list

The list shows every migration, newest first.

| Column | What it shows |
|---|---|
| **Migration** | The CRM it imports from, such as "HubSpot import" |
| **Status** | **Draft**, **Queued**, **Fetching**, **Importing**, **Completed**, **Completed with errors**, **Failed** or **Cancelled** |
| **Progress** | How many records have been imported, out of how many were read from the other CRM |
| **Errors** | How many records could not be imported |
| **Created** | When the migration was created |
| **Last run** | When it last ran, or **Never** |

Click a row, or **Open** from its actions menu, to open the migration at the step it has reached. A
migration that is still a **Draft** has never run, and **Delete** in its actions menu removes it. A
migration that has run cannot be deleted.

## Starting a migration

**New Migration** opens the migration wizard. It has six steps: **Connect**, **Choose data**,
**Map fields**, **Review**, **Import** and **Report**. You move between steps with the **Continue**
and **Back** buttons. **All Migrations** returns to the list.

![The first step of a new migration: choosing the CRM to import from](https://clockworkcrm.blob.core.windows.net/public-internal/docs/admin/admin-crm-migration.png?v=6bef9d58)

### Connect

Choose the CRM to import from:

| CRM | What can be imported |
|---|---|
| **HubSpot** | Contacts, companies, deals, tickets, notes, emails, calls, meetings, tasks and messages |
| **Pipedrive** | Persons, organisations, deals (including leads), notes, mail, calls, meetings and tasks |
| **Capsule** | People, organisations, opportunities, cases, notes, emails, calls, meetings and tasks |

Then connect in one of two ways:

- **Connect with HubSpot**, **Connect with Pipedrive** or **Connect with Capsule** opens a window
  where you sign in to that CRM and approve read access. If the window is blocked, allow pop-ups for
  the site and try again.
- Paste a token instead, then click **Validate and connect**. The token is stored encrypted and is
  never shown again.

| CRM | Token option | What you need |
|---|---|---|
| HubSpot | **Use an access token instead** | A service key from **Settings, Integrations, Service Keys** in HubSpot, or a legacy private app token |
| Pipedrive | **Use an API token instead** | Your personal API token from **Settings, Personal preferences, API** in Pipedrive, and your **Company domain**, the subdomain in your Pipedrive address |
| Capsule | **Use an API token instead** | A personal access token from **My Preferences, API Authentication Tokens** in Capsule |

A HubSpot token needs these scopes: `crm.objects.contacts.read`, `crm.objects.companies.read`,
`crm.objects.deals.read`, `tickets`, `crm.objects.owners.read`, `crm.schemas.contacts.read`,
`crm.schemas.companies.read` and `crm.schemas.deals.read`. Two more are optional:
`sales-email-read` imports email bodies and `files` imports file attachments. Without them,
everything else still imports.

Once connected, a green message confirms it. If any scopes are missing, they are listed, and the
items that need them are skipped. Click **Continue**.

### Choose data

Clockwork CRM reads the other CRM and shows how many records of each type it holds. A count ending
in + is a minimum. Tick the types to import. All of them are ticked to start with.

**When a contact or company already exists**: decide what happens when an imported contact has the
same email address as an existing person, or an imported company has the same name as an existing
company. You have the follow options to choose from:

| Option | What happens |
|---|---|
| **Keep the existing record and link the import to it (recommended)** | The existing record is kept as it is. Imported deals, notes and activity are linked to it |
| **Update the existing record with values from...** | The existing record's fields are overwritten with the imported values. Running the migration again also refreshes records imported before |
| **Always create a new record (the duplicate finder runs afterwards)** | A new record is created every time. A person whose email address is already in use cannot be created and is reported as an error |

This choice only applies to contacts and companies. Deals, tickets and activity are matched by
their ID in the other CRM, so running a migration again never duplicates them.

You also have a couple of extra options to select:

| Toggle | What it does |
|---|---|
| **Import file attachments** | Imports files attached to notes, calls, meetings and emails. On by default |
| **Import call recordings** | Imports call recordings. On by default |

**Continue** saves your choices and moves to the next step.

### Map fields

This step decides where the other CRM's properties, pipelines and owners go in Clockwork CRM. It
has a tab for each type you chose.

The mapping is applied when a record is first imported and reused on every run. Changing it later
only affects records that have not been imported yet.

**Contacts**, **Companies**, **Deals** and **Tickets** list the custom properties found in the other
CRM. Each property has an action:

| Action | What it does |
|---|---|
| **Map to existing field** | Imports the value into a field you choose from the **Target** list. Offered for contacts and companies only |
| **Create as custom field** | Creates a new custom field of the type chosen under **Target**: **Text**, **Multi-line text**, **Number**, **Currency**, **Date**, **Dropdown**, **Multi-select**, **Checkbox**, **Email**, **Phone** or **URL** |
| **Skip** | The property is not imported |

A property with the same name or label as an existing field is mapped to it automatically. The rest
are set to **Create as custom field**, with a field type that matches the property. The number of
skipped properties is shown under the table.

**Pipelines** lists the deal pipelines and ticket pipelines. For each one, choose a **Target**:

- **Create new sale pipeline** or **Create new case type** creates the pipeline and all its stages
  in Clockwork CRM.
- **Map to** an existing sale pipeline or case type. Each stage then gets its own list, where you
  choose an existing status or **Create new status**.

**Owners** lists the users who own records in the other CRM. Each owner is matched automatically to
the Clockwork CRM user with the same email address. **Override** assigns an owner's records to a
different user. An owner with no match shows **No match. Records will be assigned to you.**

### Review

The review shows how many records of each type will be imported. Click **Start Migration** to begin.

### Import

The import shows the overall percentage and a card for each record type, with how many records have
been imported so far. Records that fail are listed under **Recent errors** as they happen. A failed
record does not stop the rest of the import.

**Cancel** stops a running migration. Records already imported stay in Clockwork CRM.

When the import finishes, **View Report** opens the report.

### Report

The report says whether the migration completed and how many records could not be imported. It shows
a count of the records imported for each type, and an **Errors and warnings** table:

| Column | What it shows |
|---|---|
| **Type** | The type of record (e.g. deal) |
| **Severity** | **Error** for a record that was not imported. **Warning** for something that was skipped or changed, such as an owner with no matching user or an attachment that could not be downloaded |
| **Detail** | What went wrong |

If a migration **Failed**, the connection to the other CRM was often lost or its token was revoked.
**Reconnect** takes you back to **Connect**, then you can run the migration again.

## What is imported and where it goes

| Imported | Becomes in Clockwork CRM |
|---|---|
| Contacts, persons, people | People |
| Companies, organisations | Companies, linked to their people |
| Deals, opportunities | Opportunities in the mapped sale pipeline, linked to their people and companies |
| Tickets, cases | Cases of the mapped case type, linked to their people and companies |
| Notes | Comments on the deal, notes on the case, or notes on the people and companies they belong to |
| Emails | Emails linked to their people and companies, with their attachments |
| Calls | Phone calls with their recording, when a recording is imported. Otherwise, completed calls in the calendar |
| Meetings | Meetings in the calendar, linked to their people, companies, deals and cases |
| Tasks | Activities in the calendar |
| Messages (HubSpot) | LinkedIn messages on the person's record, and SMS on the person's or company's record. WhatsApp messages become notes |

Imported records keep their original dates, so they appear in the right place on timelines. Each
record is assigned to the user its owner was mapped to.

The import also adds:

- a tag named after the CRM, such as **HubSpot Import**, on every imported person and company
- a field group named after the CRM, holding the new custom fields
- an ID field, such as **HubSpot ID**, holding each record's ID in the other CRM, on people,
  companies, opportunities and cases

Imported calls and SMS are recorded against a number named after the CRM, such as
**Imported (HubSpot)**. It cannot be used to make calls or send messages.

## Running a migration again

**Run again** on the report takes you back to **Choose data**. Running again reads the other CRM
again and imports anything new. Records already imported are skipped. To refresh people and
companies you have already imported, choose **Update the existing record** under **When a contact
or company already exists** first.

A record you have deleted in Clockwork CRM since it was imported is not imported again.

## After a migration

When a migration completes, the duplicate finder scans your people and companies for duplicates.
See [Finding and merging duplicates](https://help.clockworkcrm.com/contacts/duplicates).

To check the result:

1. Read the **Errors and warnings** table on the report.
2. Filter people and companies by the import tag, such as **HubSpot Import**, to see what was imported.
3. Check the new sale pipelines, case types and custom fields the migration created.

## Related

- [Importing contacts](https://help.clockworkcrm.com/contacts/importing), for contacts in a CSV file
- [Finding and merging duplicates](https://help.clockworkcrm.com/contacts/duplicates)