Importing contacts

Instead of adding contacts one at a time, you can import a whole list from a spreadsheet file. Upload a .csv or .xlsx file (up to 50 MB) and the app walks you through matching its columns to your contact fields, checking for duplicates, and previewing what will happen before anything is actually saved.

Steps

1. Open the composer (the message box you use to chat or start a campaign) and click the + menu. (A segment's chat, where you describe or refine a segment, has no import option — import from Pulse or a campaign's chat.)
2. Choose Import contacts file.
3. Select a .csv or .xlsx file from your computer. The app rejects files of the wrong type or larger than 50 MB before uploading, so you'll know right away if something needs fixing.
4. An import card appears where you can review and adjust the plan:
   • Column mapping — each column from your file is matched to a contact field (built-in or custom). Accept the suggested matches, point a column at a different field, or create a brand-new custom field on the spot for a column that doesn't have a home yet. Each field takes one column: once a column claims a field, that field disappears from the other columns' menus, so two columns can't quietly overwrite each other.
   • Company and organizations — map your company column to Organization (by name) — a column headed Company, Organization or Account is matched to it for you — to link each contact to an organization: first by the domain of the contact's work email, then by the company name, and the organization is created when nothing matches. Values like “n/a” or “self-employed” are skipped. If your file has the company's website or domain in its own column, map it to Company domain so contacts are matched by it first; a domain on its own only links a contact to an organization you already have — it never creates one — and a free email domain such as gmail.com is ignored. A company name longer than 200 characters makes the whole row an error, even for a contact you already have: shorten it and import that row again. An import never moves a contact who is already linked to an organization — change that on the contact's profile.
   • Value mapping — when a column is matched to a dropdown field (Lifecycle stage, Lead source, Salutation, Preferred channel, or a custom dropdown of your own), its values have to line up with that field's options. The app does this for you: on upload it reads the column's distinct values, reuses any that already match an option by name, and adds the rest as new options on the field. Use Options on the mapping row to review the result or map a value somewhere else by hand. Columns with a lot of different values are left alone — that usually means the column is pointed at the wrong field — and the preview tells you so.
   • Match key — choose how the app recognizes a contact you already have: by email, by phone, or by a custom field. This is what determines whether a row is "new" or a "duplicate" of someone already in your account.
   • Duplicate handling — choose what happens when a row matches an existing contact:
     • Update empty fields only — fill in blanks on the existing contact without overwriting anything they already have.
     • Overwrite — replace the existing contact's values with the ones from the file.
     • Most recent wins — whichever record was updated more recently keeps its data.
     • Skip existing — only add brand-new contacts, and leave existing ones untouched.
   • Subscription consent — optional, and off unless you choose otherwise. If these contacts opted in to email somewhere else — a sign-up sheet, a trade-show booth, a system you're moving off — you can subscribe them to one of your lists as part of the import and record where that consent came from. Note that only lists with double opt-in switched on are offered here, and double opt-in isn't generally available yet — so this option isn't usable today. See Double opt-in for exactly what it does and doesn't do.
   • Silent import — on by default, and worth understanding before you turn it off. A silent import quietly adds and updates records and nothing else. Turn it off and the import runs live: every contact it adds or changes can start a journey that's listening for new or updated contacts, and every organization it creates can start one listening for new organizations, which for a large file can mean enrolling thousands of contacts at once. The summary line on the import card always tells you which mode you're in.
5. Once you're happy with the mapping and settings, the app shows a preview with counts of rows that are ready to import, flagged as errors, matched as duplicates, or skipped. The preview also tells you what won't be imported, and you have to deal with it before the import will start:
   • a column mapped to a dropdown field whose options don't cover its values — it would import as empty, so the preview names the column and shows examples;
   • a column with data and no field at all — the Columns with no field tile counts these, and the preview names the ones that actually carry data. Confirming the preview is your acknowledgement that those values are being left behind; create a field for them first if you want to keep them.
6. Start the import. You'll see it move through in progress to done, with a final report of what happened.
7. If any rows had problems, download the error rows to see exactly which ones and why, fix them in your file, and re-import just those.

Importing from a session

You can also hand the file to the assistant instead of walking the wizard. Attach the file in any session and say what you want:

• "import contacts @[Uploaded file name]"
• "Import the contacts from the file I just uploaded. Show me a preview before writing anything."

@[Name] stands for an @-mention of the uploaded file — see Pointing at your own data. The assistant runs the same preview-then-commit sequence the wizard does: nothing is written until you've seen the preview and confirmed it.

Tips

• Give your columns clear, simple headers (like "Email" or "Phone") before uploading — it makes automatic column matching more accurate, so you have less to fix by hand.
• Double-check your match key choice before importing a large file: it decides whether returning contacts get updated in place or accidentally duplicated.
• You can add tags or a segment to every contact from a given import as part of the same flow, which is a fast way to group a freshly imported list for a welcome campaign.
• Large files take a little time to process — you can leave the import running and come back to check its progress.

FAQ

Q: What file formats are supported? A: .csv and .xlsx, up to 50 MB per file.

Q: What if a column in my file doesn't match any existing field? A: It is not imported — nothing creates a field for it automatically. The preview counts these under Columns with no field and names the ones carrying data, and the final report lists them too. To keep a column, create a field for it at the mapping step (Create new field… on that row) before you confirm — see Custom fields for what that means for the rest of your account. If you don't need the column, confirming the preview is you saying so.

Q: How do the company names in my file become organizations? A: Each contact is linked to the organization that matches its work email domain or its company name, and an organization is created for a company you don't have yet. Placeholder values such as “n/a” never create one. See Organizations. With a CRM connected and organization sync on, an import that links contacts to an organization sets their account in your CRM, and a company that has no account there yet gets one; an import that only updates other columns changes no one's account and creates none.

Q: Will importing send anything to the contacts I'm adding? A: No. Importing only adds or updates contact records — it never sends an email, SMS, or notification on its own. That holds even when you use Subscription consent to subscribe them to a list: no confirmation emails are sent, however big the file.

Q: What is the Subscription consent option for? A: For contacts who already opted in to your email somewhere outside the app. You pick the list, write down where the consent came from, and the import subscribes them and stores your note as the record of it. Both parts are required together — a list without a note won't save. Leave it alone and the import touches no subscriptions at all. Full detail in Double opt-in.

Note: the list picker only offers subscription lists that have double opt-in switched on, and double opt-in isn't generally available yet — so in practice this option can't be used today. See Double opt-in.

Q: Can an import trigger an automation that sends something? A: Not on its own — an import never composes or sends an email or SMS by itself. With Silent import left on (the default), that's the whole story: records are added and updated, and nothing else happens. If you turn Silent import off, the import runs live and the contacts it adds or changes can be picked up by journeys that trigger on new or updated contacts — and those journeys can send. So the sending, if any, comes from your journeys, not from the import. See Triggers.

Q: What happens to rows that fail? A: They're excluded from the import and counted separately in the preview and final report. You can download just the failed rows, correct the issue, and re-import them.

Q: My contacts imported, but one column came through empty. Why? A: That column is matched to a dropdown field whose options don't include the column's values. A row only fails when the contact can't be created; a value the field won't accept is dropped and the row still imports, which is why the counts can look clean. The final report lists each affected column and the values that were refused. Fix it by opening Column mapping, using Options on that row to map its values onto the field's options — or pointing the column at a different field — and re-importing the same file. Re-importing updates the contacts that are already there, so the values fill in; it does not create duplicates.

Q: Can I import a column of tags, or my own signup dates? A: Not as tags or as the contact's created date — neither is available as a mapping target. You can keep the values by creating a custom field for the column at the mapping step, and you can apply the same tags or segment to everyone in the import from the import card. See Custom fields.

Related guides

• Contacts overview