A field mapping is the document that records, for every Salesforce field you intend to keep, where it lands in HubSpot, how the value is transformed on the way, and how you will prove it arrived intact. It is the control that prevents data loss in a CRM migration. Most migrations that go wrong skipped it or kept it in someone's head.
This is the checklist version, organized by object. For the surrounding plan, timeline, and cutover, see the complete migration guide.
The short version: Map every field you keep, one row each, with a transformation rule and a validation check. Match records on the Salesforce ID, not on names. Translate picklists by value, not label. Treat opt-outs, owners, and dates as the three highest-risk field groups. Prove every mapped field with counts, sums, and a sample read before cutover.
The mapping document: columns to include
| Column | What goes in it |
|---|---|
| Salesforce object and API name | The field's API name, not its label. Labels get renamed. API names do not. |
| Data type and fill rate | Picklist, date, currency, and so on, plus the percentage of records populated. |
| Target HubSpot object and property | The internal name, field type, and whether it already exists or must be created. |
| Transformation rule | Trimming, case, date format, value map, split or merge. Written as a rule, not "clean it up". |
| Required or unique | Whether the property must be populated or must hold unique values. |
| Decision owner | The named person who approved the mapping, in sales, marketing, or finance. |
| Validation check | The specific test that proves the field migrated: count, sum, distinct values, or sample. |
| Status | Unmapped, mapped, built in HubSpot, loaded in test, validated. |
Any field with a fill rate under 5 percent and no named owner is an archive candidate. Do not map it.
Checklist by object
Accounts to companies
- Domain: strip protocol, "www", and paths so the value is the bare domain. HubSpot uses company domain name as the unique key and only accepts values up to the top-level domain.
- Salesforce Account ID stored in a unique-value property.
- Parent account mapped to a parent and child company association.
- Account owner matched to an existing HubSpot user by email.
- Industry, type, and rating picklists mapped value by value.
- Record type: decide whether it becomes a property, a separate company type, or is retired.
- Billing and shipping address split into the right address properties.
- Created date and last modified date stored in custom date properties.
Contacts to contacts
- Email: lowercase, trimmed, validated. It is HubSpot's default unique key.
- Secondary or personal email fields decided explicitly, not silently dropped.
- Salesforce Contact ID stored in a unique-value property, which also covers contacts that have no email.
- Account relationship rebuilt as a company association using the Account ID.
- Phone numbers standardized to one format.
- Lead source and contact status picklists mapped, with a decision on retired values.
- Email opt-out, do-not-call, and subscription flags migrated. A lost opt-out is a compliance problem, not a data problem.
Leads to contacts
- Converted leads excluded. The contact record created at conversion is the one that migrates.
- Lead status mapped to HubSpot lead status and lifecycle stage together, using documented definitions.
- Leads owned by a Salesforce queue assigned to a named user or a team rule, since queues have no HubSpot equivalent as an owner.
- Lead source and campaign attribution mapped to original source properties or custom properties.
Opportunities to deals
- Pipeline: record types or sales processes mapped to HubSpot pipelines.
- Stage: every Salesforce stage mapped to a HubSpot stage, with probability aligned.
- Amount and currency: confirm whether amounts are stored in corporate or deal currency, and map accordingly.
- Close date: confirm the time zone treatment, then check every date within a week of a quarter end.
- Type, forecast category, lead source, and next step mapped.
- Lost reason migrated as a picklist, with free-text variants consolidated.
- Description and long text fields checked for length against the target property.
- Contact roles rebuilt as deal-to-contact associations with labels where your tier supports them.
- Created date and stage-entry dates from OpportunityHistory stored in custom date properties.
Activities
- Task subtype (call, email, other) mapped to the correct HubSpot activity type.
- Salesforce uses WhoId for the person and WhatId for the account or opportunity. Map both to HubSpot associations.
- Activity owner and date preserved.
- Notes and attachments: decide whether files migrate or stay in the archive.
- Load once. Import creates new activities and cannot update existing ones.
Products, quotes, and custom objects
- Products and price book entries: decide how list price, discounts, and currency are represented, since price books have no direct HubSpot equivalent.
- Opportunity line items mapped to deal line items.
- Quotes: decide whether history migrates or stays in the archive.
- Each custom object assigned to a HubSpot custom object (Enterprise), a property set on an existing object, or the archive.
Users and owners
- Every active user created in HubSpot before any record load.
- Inactive users who own closed deals mapped to a placeholder owner or a named successor, so history stays attributed.
- Teams and permission sets built before go-live, not after.
Field-type translation rules
| Salesforce type | HubSpot type | Watch for |
|---|---|---|
| Picklist | Dropdown select | Map internal values. Mismatched values load as blanks. |
| Multi-select picklist | Multiple checkboxes | Salesforce and HubSpot both use semicolon-separated values. Confirm every option exists in HubSpot first. |
| Checkbox | Single checkbox | True and false only. Decide what null means. |
| Date | Date picker | Format and time zone. A one-day shift can change a quarter. |
| Date and time | Date and time picker | Salesforce stores UTC. Confirm the display time zone. |
| Currency | Number or deal amount | Multi-currency orgs need a conversion rule, stated and tested. |
| Formula | Calculated property, workflow, or static value | The logic does not migrate. Rebuild it or load a snapshot. |
| Roll-up summary | Calculated property or workflow | Rebuild from associations. Calculated properties need Professional or Enterprise. |
| Lookup or master-detail | Association | Rebuild from IDs, then count associations to verify. |
| Long text area | Multi-line text | Check for truncation against the target limit. |
| Auto-number | Single-line text | Keep as text so leading zeros and prefixes survive. |
Validation checks for every mapped field
- Null counts match. The number of blank values in Salesforce equals the number in HubSpot, after documented exclusions.
- Distinct values match. For picklists, the list of values and their counts agree after mapping.
- Sums and ranges match. For currency and numbers, totals tie out. For dates, the minimum and maximum agree.
- Keys are unique. Zero duplicates on the Salesforce ID, email, and domain.
- Associations tie out. Contacts per company, deals per company, and deals per contact agree for a sample of 50 accounts.
- Sample read. Open 50 to 100 random records in both systems and compare field by field.
- Rerun test. Run the full load in a sandbox twice. The second run should change nothing.
Sign-off before the production load
- Sales leadership approves the deal fields, stages, and pipeline mapping.
- Marketing approves contact, lead source, and opt-out handling.
- Finance approves amount, currency, and close date treatment.
- Someone with authority approves the list of fields that will not migrate.
- The sandbox load passed every check above.
Frequently asked questions
- What is a field mapping in a CRM migration?
- A field mapping is a document that lists every source field, the destination property it loads into, the transformation applied, and the check that proves it migrated correctly. It is the main control against data loss.
- What is the most common field mapping mistake in a Salesforce to HubSpot migration?
- Mapping picklist labels instead of values. The load completes without errors, but mismatched values arrive as blanks, and the loss only shows up later in reporting.
- How do you preserve pipeline history during field mapping?
- Map closed deals along with open ones, and store original created dates, close dates, and key stage-entry dates in dedicated custom date properties. Do not rely on HubSpot to reconstruct them.
- Which fields should not be migrated?
- Fields with very low fill rates and no owner, formula fields whose logic will be rebuilt, and legacy fields tied to retired processes. Keep them in a full Salesforce export instead.
- How do you match records between Salesforce and HubSpot?
- Store the Salesforce ID in a unique-value property on each object and use it as the identifier for every import. Matching on names or partial emails creates duplicates and broken associations.
- How many records should you sample when validating a CRM migration?
- Reconcile totals on every field, then read 50 to 100 random records side by side. Increase the sample for any object where totals did not tie out on the first pass.