A CRM migration is ready when the right records, relationships, permissions and next actions work in the destination, not when an upload finishes. Start with a small approved cohort, map its identity and fields, test the result, then decide whether to move the next cohort.
This CRM migration checklist gives you a field map, a worked reconciliation and a cutover worksheet. It is a planning method, not a promise that any one CRM can import every object, activity or automation from another.
Decide what is moving before preparing a file
Write one sentence naming the source, destination, record types and business process. “Move our active partner contacts and their company relationships” is testable. “Move the CRM” leaves room for different people to expect email history, attachments, permissions, reports and live automations that were never included.
For each object, record whether it will be imported, recreated manually, retained read-only in the old system or excluded. A useful object list includes contacts, companies, deals, notes, tasks, documents, communication history, custom fields and automation rules. These are inspection categories, not features every destination supports.
- Business owner: decides which work must continue after the switch.
- Data owner: approves which records and fields may move.
- Migration operator: prepares files and performs approved operations.
- Receiving owner: checks that the destination supports the actual next job.
- Rollback owner: knows what can be reversed and who can authorize it.
One person can fill more than one role. What matters is that “someone will check” becomes a named responsibility. Do not export confidential records simply because an administrator can see them.
Make identity and relationships explicit
Keep the source system's stable record ID in your working crosswalk. Map it to a destination ID after a test import. Names are not a reliable identity key: two people can share a name, companies can rename, and one person may have several email addresses.
The destination's own rules determine which identifiers and associations it accepts. For example, HubSpot documents separate requirements for unique identifiers and record associations. That is a concrete reason to inspect object-specific import documentation rather than assume the same spreadsheet works everywhere.
Choose a matching policy before running the import. Decide how to treat an existing destination record, a shared address, a blank identifier and a changed company relationship. If a row cannot be matched safely, hold it for review rather than guess.
A small synthetic dataset that catches identity mistakes
The following rows are entirely fictional. The .test addresses are reserved examples, not people to contact. Two source contacts share an email and one has no stable company identifier. The safe treatment is to preserve the ambiguity for review, not merge by email or guess a company from its display name.
| Source contact ID | Company ID | Test decision | |
|---|---|---|---|
| C-101 | team@example.test | CO-10 | Hold with C-102 until identity policy is resolved |
| C-102 | team@example.test | CO-11 | Shared email does not prove the same person |
| C-103 | riley@example.test | Missing | Do not invent an association; obtain the stable key or exclude association |
| C-104 | casey@example.test | CO-10 | Eligible for the defined test if all other permissions and field checks pass |
In this four-row test, one row is eligible, three are held, and no source row has disappeared. The expected association count for the eligible cohort is one. That is a separate teaching case from the 12-contact reconciliation below; do not combine their denominators.
Blank source-to-target crosswalk
Source record
Object: [object]
Stable ID: [identifier]
Field: [field name]
Value type: [type]
Destination
Object: [supported object]
Field: [supported field]
Value type: [supported type]
Identity match: [source key and destination matching rule]
Relationship key: [related record ID or not applicable]
Transfer rules
Transformation: [explicit rule]
Blank values: [how null or missing values are handled]
Operation: [create, update, archive or exclude]
Hold or exclusion reason: [reason or not applicable]
Acceptance and approval
Checks: [value, identity, relationship and permission evidence]
Approving owner: [name]
Crosswalk version: [version]Here is an illustrative field map for a fictional team. Replace these fields with the documented fields in your actual systems.
| Source value | Destination treatment | Acceptance check |
|---|---|---|
| Contact record ID | Keep in the migration crosswalk; map to the returned destination contact ID. | Every approved source contact has exactly one intended destination match. |
| Company record ID | Map to the destination company identifier separately from company name. | The contact belongs to the intended company, including any approved multiple relationships. |
| Pipeline stage | Use a reviewed source-to-target stage dictionary. | Each transferred stage has a documented meaning; unknown stages are held. |
| Owner | Map to a current authorized destination user, not a name guessed from a label. | The receiving owner can see the record and perform the permitted next action. |
| Next action and due date | Map only if the destination supports the required fields and date behavior. | Task meaning, date and timezone display agree with the approved source. |
| Sharing restriction | Preserve with an equivalent supported control or keep the record out of scope. | A user who should not see the record cannot see it in the destination. |
Do not silently flatten a restriction into a text note and treat that as equivalent access control. If a permission cannot be preserved, change the scope or obtain a reviewed plan before proceeding.
Build a test cohort that can fail usefully
A test made only of clean, new contacts proves very little about the difficult parts of a migration. Include permitted examples of the edge cases your business actually has: an existing destination match, a changed company name, an inactive owner, a blank optional field and a record with restricted visibility. Use synthetic data first when real records are unnecessary.
- Save a dated, access-controlled source snapshot and a destination baseline for the fields you may change.
- List the exact source IDs included and excluded, with the reason for each exclusion.
- Document the proposed create, update and association operations. Do not mix an update test with untracked new records.
- Check whether imports trigger emails, sequences, workflows or notifications. Use an approved test environment or controlled plan that prevents unintended actions.
- Run the smallest useful test and retain the operation receipt and returned IDs.
- Re-read the resulting records. Compare what exists, not just the importer’s success message.
A successful test is not permission to move the whole database. It is evidence for the next decision.
Worked example: the count passes, but the migration fails
Illustrative example: Harbor Lab is moving an approved pilot cohort from one CRM to another. The source export contains 14 contact rows. The owner excludes one archived record and one record not approved for this transfer. The cohort is therefore 12 contacts linked to three companies. All 12 are new to the isolated destination test.
The first import creates 12 contacts and three companies. The operator could call that complete. A relationship comparison instead finds that two contacts were attached to a similarly named company rather than the company identified in the source.
| Check | Expected for the approved cohort | First test | Decision |
|---|---|---|---|
| Contact count | 12 | 12 | Count passes; other checks still required. |
| Company count | 3 | 3 | Count passes; names alone do not prove identity. |
| Correct contact-to-company relationships | 12 of 12 | 10 of 12 | Hold the migration. |
| Excluded contacts transferred | 0 | 0 | Exclusion check passes. |
| Unintended outbound actions | 0 | 0 | Control check passes. |
The team inspects the crosswalk. Contacts C-004 and C-007 should map to company CO-02. The file used a display name that also matched CO-03. The operator corrects the approved mapping using the documented destination identifier and repeats the affected test under the rollback owner's plan.
The second reconciliation shows 12 contacts, three companies and 12 of 12 correct contact-to-company relationships. The two excluded contacts remain excluded. The receiving owner opens the affected records and checks visibility and next actions. Only then does the business owner approve a larger cohort.
The lesson is specific: equal record counts can coexist with the wrong relationship graph. Preserve identifiers and verify relationships separately.
Reconcile meaning, not just rows
Use three levels of comparison. First, reconcile counts for the exact cohort: approved source rows, intended creates, intended updates, exclusions and failures. Next, reconcile identity and associations. Finally, inspect the business meaning of fields that influence work.
- A stage called “Committed” must not become “Interested” because both occupy the fourth position in a list.
- A missing owner must not silently become the importing administrator.
- A blank value must not erase a reviewed value unless that is the approved operation.
- A date that displays correctly in one timezone must not become the wrong day's task for the receiving owner.
- A note retained in an archive must not be reported as migrated searchable history.
Record unresolved differences individually. “Mostly correct” is not an acceptance result if the exception concerns access, identity or an important commitment. You can approve a smaller clean cohort while keeping unresolved rows out of scope.
Copy this cutover and rollback worksheet
Complete the worksheet before the production operation. Put access-controlled evidence links in the private working copy, not in a public document.
| Decision | Your entry | Evidence or owner |
|---|---|---|
| Source, destination and business job | [Systems, objects and job] | [Business owner] |
| Approved cohort and exclusions | [Exact IDs or controlled file; exclusion reasons] | [Data owner approval] |
| Field and identity map | [Version; matching and blank-value rules] | [Reviewed crosswalk] |
| Destination baseline | [Snapshot of fields and associations that may change] | [Capture time and restricted location] |
| Changes during the transfer | [Freeze, or explicit change log and delta reconciliation] | [Owner and cutoff] |
| Automation and outbound controls | [What can trigger; how unintended actions are prevented] | [Verified configuration and authorized operator] |
| Acceptance criteria | [Counts, identity, relationships, permissions and next-job checks] | [Receiving owner] |
| Stop conditions | [Mismatch or unexpected action that stops the batch] | [Decision owner] |
| Rollback boundary | [New records versus existing fields; supported reversal method] | [Rollback owner and tested receipt] |
| Final decision | [Proceed, restrict the cohort, fix and retest, or stop] | [Decision time and approval] |
“We have a backup” is not a rollback procedure. Know how to identify records created by this operation, which existing values changed and what to do if someone edited a destination record afterward. Restoring an old snapshot over a concurrent edit can destroy newer work. Stop and reconcile that conflict rather than overwrite it automatically.
Handle the final change window
If people continue editing the source during the transfer, record changes after the snapshot and reconcile that delta. Otherwise the target can be accurate at the snapshot time and already incomplete at cutover. Agree whether the source is temporarily read-only, who can make exceptions and where those exceptions are logged.
Keep the old system available under an approved retention/access plan until acceptance is complete. Do not delete source records, cancel an account or switch on customer-facing automations merely because a file imported. Those are separate decisions with their own owners.
Troubleshoot before repeating an import
| Symptom | Inspect first | Next decision |
|---|---|---|
| Unexpected duplicate contacts | Matching mode, unique identifiers and whether the operation created rather than updated. | Stop retries; identify exact affected IDs and approve a correction before another import. |
| Correct counts, wrong companies | Association identifiers and similarly named records. | Fix the mapping and verify each affected relationship. |
| Owners cannot see records | User mapping, membership and sharing scope. | Hold the cohort; do not broaden access as a convenient workaround. |
| Old task dates or lost notes | Field support, timestamp behavior and whether the object was actually in scope. | Preserve the source; document the gap and choose a supported alternative. |
| A retry changes newer target data | Baseline, operation receipt and concurrent edits. | Stop the batch and reconcile with the receiving owner. |
Know when you can call the migration accepted
The receiving owner should be able to choose an approved record, identify why it is there, confirm its relationships and permissions, and perform the next intended job. The operator should be able to explain every failure, exclusion and change since the baseline.
- The approved cohort is reconciled, with no unexplained identity or relationship differences.
- Restricted records remain restricted and excluded records remain excluded.
- Important stages, owners and next actions preserve their intended meaning.
- The test and production receipts identify what was created or changed.
- The team has a usable plan for unresolved gaps and concurrent edits.
If you are evaluating whether to switch tools at all, start with the fundraising CRM comparison. If the immediate problem is cleaning the CRM you already use, review CRM data quality with Codex before treating migration as the fix.
Keep the people, evidence and next decisions together as you plan the move. Verify the destination's current import and access controls against your actual requirements before transferring production data.