What is a CRM migration checklist?
A data project, not an import button. Inventory, map, dedupe, dry run, reconcile, then cut over with a freeze window.
The short answer
- A CRM migration is a data project: inventory every object and field in the source system, map them to the new system, dedupe the records, migrate in a dry run first, reconcile the counts, then cut over with a freeze window.
- Most migration failures come from unmapped custom fields and duplicate contacts, not from the import mechanism itself; the import tool usually works fine on data that was mapped and cleaned first.
- A dry run into a test environment, checked against the source record counts, catches mapping and dedupe problems while they are still cheap to fix, before the cutover makes the new system the system of record.
- The freeze window, a short period where the old system stops accepting new changes while the final migration and reconciliation happen, is what prevents records created during the move from being lost.
Why most failures are not about the import tool
Almost every CRM offers a way to import a CSV, and almost every migration failure people report has nothing to do with that import step. The failure happens earlier: a custom field in the old system had no obvious home in the new one and got dropped silently, or two records for the same contact both migrated and now the new system has duplicates the old one did not.
Treating a migration as a data project rather than a one-time upload changes what work happens first. The inventory and mapping steps take longer than the import itself, but they are what determines whether the import produces a clean result or a mess that takes weeks to untangle by hand afterward.
The 12-step checklist
Roughly in order. Steps 1 to 5 take the most time and prevent the most problems.
- 1
1. Inventory the objects
List every object type in the source system: contacts, companies, deals, tasks, notes, custom objects. Note the record count for each.
- 2
2. Inventory the fields
For each object, list every field, including custom ones added over the years. This is where forgotten fields live.
- 3
3. Map fields to the new system
Match each source field to a destination field. Flag anything with no match and decide: create a new field, merge into an existing one, or drop it deliberately.
- 4
4. Identify relationships
Note how objects link: which fields connect a contact to a company, a deal to a contact, a note to a record. These links are the easiest thing to lose in a flat CSV export.
- 5
5. Find and resolve duplicates
Dedupe in the source system before migrating, using email or another reliable unique field. Migrating duplicates moves the same problem into the new tool.
- 6
6. Export from the source
Pull a full export, ideally a database dump if the source system offers one, otherwise CSVs per object with IDs preserved for relationship mapping.
- 7
7. Set up the destination structure
Create custom fields, pipeline stages and object types in the new system to match the mapping from step 3, before importing any records.
- 8
8. Run a dry run
Migrate into a test environment or a small sample first. Check that fields landed correctly and relationships held.
- 9
9. Reconcile counts
Compare record counts between source and dry-run destination, object by object. A mismatch means something did not map or was silently dropped.
- 10
10. Migrate activity history
Emails, calls, notes and timeline events are commonly the first thing skipped. Confirm explicitly whether the migration plan includes them, since many tools default to skipping activity data.
- 11
11. Freeze and cut over
Set a short freeze window where the old system stops accepting new changes, run the final migration, and reconcile counts one more time before declaring the new system live.
- 12
12. Verify with the team
Have a few real users check their own records in the new system before the whole team switches over. They catch mapping problems a count comparison misses.
What breaks and why
| What breaks | Why it happens | How to catch it |
|---|---|---|
| Custom fields disappear | No mapping decision was made before the import ran | Complete the field inventory and mapping in steps 2 and 3 before touching the destination system |
| Duplicate contacts appear | The same person existed as two records in the source and both migrated | Dedupe in the source system in step 5, before export |
| Deals lose their contact link | The relationship was stored as an internal ID that did not carry over correctly | Verify relationship mapping in the dry run, step 8, before the real cutover |
| Activity history is missing | Many import tools default to standard objects only and skip emails, calls and notes | Confirm explicitly in step 10 whether activity history is included in the migration plan |
| Records created during the move go missing | No freeze window, so the source system kept changing while the export was already taken | Use a freeze window in step 11 so nothing changes between the final export and the cutover |
Activity history is the thing vendors quietly skip
Questions
- How long does a typical CRM migration take?
- It depends heavily on record count, the number of custom fields, and how clean the source data already is. A small team with a few thousand contacts and simple fields can move in days; a larger account with years of custom fields and duplicates can take weeks of mapping and reconciliation before the cutover.
- Should I clean up duplicates before or after migrating?
- Before, if possible. Migrating duplicates just moves the same problem into the new system, and deduping after the fact is harder once records have picked up new activity in two places at once. A dry run is the right point to catch and resolve them.
- What is the single most common cause of a failed migration?
- Unmapped custom fields. Standard objects like contacts and deals map cleanly between most CRMs; the custom fields a team added over the years rarely have an obvious match in the new system, and skipping the mapping step is how that data quietly disappears.