What is a data migration mapping sheet?
A data migration mapping sheet is a table that records, for every field you move, where it comes from, where it goes in HubSpot, what it means, and how its values change on the way. It also captures matching keys, associations, and test results, so the migration is a documented agreement rather than an improvised upload.
Migration quality is decided before the first import. We use this sheet on every migration we run, whether the source is Salesforce, Pipedrive, Zoho, or a spreadsheet. Below is each column, why it exists, and how to fill it in.
Get the template: the Data Migration Mapping Sheet, a fillable PDF workbook. Enter your name and email and the download starts straight away.
We'll also send occasional HubSpot tips by email. Unsubscribe anytime. See our privacy policy.
Thanks, your download should start now. Download the fillable PDF or the spreadsheet (XLSX).
The spreadsheet has the six tabs described below, with dropdowns for data type, decision and matching key, example rows and a cutover log with the import order already listed.
Which columns should a mapping sheet include?
At minimum: source object and field, target object and property, business meaning, data type, allowed values, transformation rule, decision (migrate, archive, calculate, exclude), matching key, owner, and test status. Each column answers a question someone will otherwise ask in the middle of cutover.
| Column | What to record | Example |
|---|---|---|
| Source object | The object in the old system | Account |
| Source field | API name and label of the field | Industry__c (Industry) |
| Target object | The HubSpot object it lands on | Company |
| Target property | Internal name of the HubSpot property, new or existing | industry |
| Business meaning | One sentence on what the field means to the business | Primary industry used for routing and reporting |
| Data type | Text, number, date, dropdown, multi-select, checkbox | Dropdown |
| Allowed values | The valid options in the target | The agreed industry list |
| Transformation rule | How values change on the way | Map each legacy value to one agreed value |
| Decision | Migrate, archive, calculate, or exclude | Migrate |
| Matching key | Whether this field identifies the record on import | No (domain is the key) |
| Field owner | Who decides what this field means and who may edit it | Sales ops |
| Test status | Result of the sample import check | Passed on the sample batch |
What tabs should the mapping sheet have?
Six tabs cover most migrations: fields, value maps for dropdowns, associations, the user-to-owner map, a test log and a cutover log. The fields tab is the core. The others hold the details that otherwise get decided in a hurry during cutover, such as what happens to old status values or to deals owned by people who have left.
| Tab | One row per | Answers |
|---|---|---|
| Fields | Source field | Where each field goes, what it means and what happens to it |
| Value map | Old dropdown value | Which new value each old value becomes |
| Associations | Relationship between objects | How records connect, and which ID rebuilds the link |
| Owners | Old user | Which HubSpot owner takes their records, including people who have left |
| Test log | Check run on a sample import | What was compared, the result and the fix |
| Cutover log | Step on cutover day | Order, who does it, the freeze window and the rollback point |
How do you map a field correctly?
Map by business meaning, not by label. A source field called "Status" may mean something different from a HubSpot property with the same name. Confirm what the field means, its data type, and its allowed values in both systems, then write the transformation rule before any data moves.
- Record source object and field alongside the target object and property.
- Define transformation rules for formats, values, dates, and currencies.
- Mark every field as migrate, archive, calculate, or intentionally exclude.
Fields nobody has filled in for a long time are usually candidates to exclude. Fields that HubSpot can derive, such as rollups and counts, are usually better calculated than imported.
How do you map dropdown values?
List every value the old field actually contains, not just the values its settings allow, with how many records use each. Then map each one to exactly one allowed HubSpot value, or mark it for review. Values with few records are often typos or retired options, and are the easiest to merge or drop.
| Old value | New HubSpot value | Decision |
|---|---|---|
| Cust - Active | Customer | Map |
| Customer (old) | Customer | Merge into the same value |
| Prospect | Lead | Map |
| N/A | (empty) | Leave blank |
| Partner? | For review | Field owner decides before the full import |
The example shows the pattern, not a recommendation for your stages. Lifecycle stage and deal stage values deserve the most care, because reports and automation depend on them. Agree their definitions first, as covered in HubSpot lifecycle stages explained.
How do you handle associations and history?
Give each object a matching key, store the source system's record ID on every imported record, and import in dependency order: owners, companies, contacts, deals and tickets, then activities. Associations are rebuilt from the stored IDs, so a record keeps its context even when names or emails change.
- Document the matching key for each object, such as email for contacts and domain for companies.
- Map associations, ownership, lifecycle, and activity history explicitly, on their own tab.
- Decide which history is required for daily work and which can be archived outside HubSpot.
- Map old users to HubSpot owners, including people who have left.
When we checked HubSpot's documentation in October 2026, HubSpot deduplicated contacts by email and companies by domain automatically, and accepted Record ID or a custom property that requires unique values as the matching key on import. Existing emails, meetings, notes and tasks can't be updated by importing again, so test activity imports on a sample before the full run.
How do you test the mapping before cutover?
Run a sample import, then compare source and target values record by record. Reconcile counts per object, check associations and owners on sample records, and confirm the critical reports return the same numbers. Log each result in the test status column and fix the mapping before the full run.
- Run a sample import and compare source-to-target values.
- Reconcile record counts, associations, owners, and critical reports.
- Document rollback, freeze windows, and post-cutover verification steps in a cutover log.
The full sequence, from audit to training, is in our Salesforce to HubSpot migration checklist. The same steps apply to other source systems.
Who fills in the mapping sheet?
The migration lead builds the sheet and fills in the technical columns. Field owners, such as sales ops for deal fields and marketing for contact sources, fill in business meaning and value maps and approve the decisions. The HubSpot admin confirms target properties and permissions. Nobody imports until every row has an owner's decision.
The mapping sheet is also the start of the new portal's documentation. Keep it after go-live: the business meanings become your property definitions, and the owners become the property owners in your HubSpot governance checklist.
Mapping sheet checklist
Use these checkpoints to turn the template into a working process.
Key takeaway: A mapping sheet turns migration from a technical upload into a shared agreement about what the new CRM should mean.
Frequently asked questions
What should a data migration mapping sheet include?
One row per field with the source field, target HubSpot property, business meaning, data type, allowed values, transformation rule, decision, matching key, owner and test status. Add tabs for dropdown value maps, associations, the user-to-owner map, a test log and a cutover log.
Should you migrate every field to HubSpot?
No. Mark every field as migrate, archive, calculate or exclude. Fields nobody fills in, fields that only existed for an old report, and values HubSpot can calculate itself rarely belong in the new CRM. Archive them in a file outside HubSpot instead, so nothing is lost.
How does HubSpot match imported records to existing ones?
HubSpot deduplicates contacts by email address and companies by company domain name. Record ID can match any record type, and custom properties set to require unique values can be used for contacts, companies, deals, tickets and custom objects. Without a matching key, an import creates new records.
Can you fix imported activities later?
Not by import. HubSpot's documentation says existing emails, meetings, notes and tasks can't be updated by importing again. Map activities carefully, test them on a sample, and import them once, after the records they belong to are in place.
Sources
HubSpot documentation behind the feature and tier notes above, checked October 2026. HubSpot changes features and tiers often, so check your own portal too.