Skip to content

Field mapping explained: matching old columns to new fields

Last checked November 14, 2026

Field mapping is the step where you tell the new system which column in your file belongs in which field. Without it, the system has a pile of values and no idea where they go.

A field is one slot in a record, like "email" or "phone". A column is the same thing as it appears in your CSV file. Mapping pairs the two.

What the import screen does

Most import tools follow the same pattern. You upload the file, the tool reads the header line, and then it shows each column next to a field choice.

One email tool's help page describes this step plainly. You match the columns in your import file to the fields in the audience.1 It also says the tool will automatically match some columns for you.1

Treat automatic matches as suggestions. A column called "Name" might be filled into a full-name field, or only a first-name field. Read each pairing.

What happens to columns you don't map

Unmatched columns are often dropped. The same help page says any unmatched columns won't be imported.1 That's a quiet failure. The import finishes and you only notice later that a column of notes never arrived.

So go down the whole list. For every column, decide: map it, create a new field for it, or leave it out on purpose.

Required fields and unique identifiers

Many systems insist on at least one field. For one contact tool, an email address is required to import email contacts.1 A CRM's guide adds that, when you're updating existing records, you must include a unique identifier.2

A unique identifier is a value that belongs to one record only. An email address, a customer number or a product code can play that role. It lets the system tell "update this person" apart from "create a new person". If your old system had its own ID column, keep it in the export.

Column order and names

Order doesn't matter much to some systems. One CRM's guide says column headers can be organized in any order without affecting the import.2 What counts is that each header lines up with a field the system knows, or that you map it by hand.

If the names differ, you can rename the header in the file or map it on screen. Renaming in the file is often tidier, because the next import will map itself.

Build a mapping table first

Before you upload anything, make a small table on paper or in a spreadsheet. It takes a few minutes and catches most surprises.

Old column New field Needs changing?
Cust Name Full name Maybe split into first and last
Tel Phone Format with country code
Joined Start date Date order
Notes Notes Check for commas and line breaks
Old ID Customer number Keep as text

Add a note for anything that needs changing in the file. Dates, phone numbers and money usually do. There's a separate page on fixing those values.

Fields with fixed choices

Some fields only accept certain options, like a status, a category or a country. The values in your file then have to match those options. One CRM's guide says values must match either the label or the internal value of the property's defined options.2

If your old system used "Active" and the new one expects "Current", the import may reject the row or leave the field empty. Fix the values in the file, or create the missing option in the new system first.

How a mapping step worksUpload the CSV fileRead the header linePair each column with a fieldSkip columns you don't needReview, then run the import
The new system pairs each file column with one of its own fields.

Blank cells

An empty cell isn't always treated as "erase this". One CRM's guide says its import tool ignores blank cells in a spreadsheet.2 The email tool's help page says the opposite for updates: blank fields overwrite and erase existing email contact data.1 So the two cited tools behave differently. If you're updating existing records, check what your own tool does with blanks before you rely on it.

Keep the mapping

Save your table with the export files. If the import has to be repeated, or someone asks months later where a value came from, you'll have the answer. Then run a small first load with a test import to see whether the mapping holds.

Notes and sources

  1. Import Contacts to Mailchimp, Mailchimp Help Center
  2. Format import files, HubSpot Knowledge Base