Importing contacts from CSV

The import wizard loads a contact spreadsheet into your organization’s directory and, optionally, into an email list. It opens from the Import CSV button under Contacts — a control only administrators see.

There are four steps, and you only move forward once the current one is complete. You can go Back at any point without losing what you already filled in.

Note

The destination list is optional. Without a list, contacts go only into the organization’s directory — which is also why the consent source stops being asked: it authorizes sending, and a batch with no sending destination has nothing to consent to.

Step 1 — Upload the file and map the columns

Pick your file under CSV file. As soon as it loads, the wizard reads the header row and builds three selectors, one per column it knows how to use:

• Email column
• Phone column
• Name column

Each accepts “No … column” when your file doesn’t have that field. Map at least one of the two identifying columns: email or phone — with neither, Continue stays disabled, because there would be no way to tell whose row it is.

The name is always optional: it enriches the record but identifies no one.

Step 2 — Destination and consent

Destination list (optional) decides where the contacts go beyond the directory. Administrators can create a list without leaving the wizard, using the create button next to the selector.

Once you pick a list, Consent source becomes required. The options are:

Source	When to use it
Own signup (website, form, or app)	The person signed up for something of yours
In-person event or webinar	The contact came from a registration or attendance list
Migration from another platform	The base lived in another email service or CRM
Purchased list	The file was bought from a third party
Unknown origin	There is no record of how the contact got in
Other	Describe the origin in the field that appears

Purchased list and Unknown origin show the warning “This source may require a compliance review.” The wizard does not block the import: it records the source alongside the batch, so the decision stays documented and auditable later.

Step 3 — Review

The review screen sums up what is about to happen: the file name, the size of the sample read, the destination list you chose (or the note that there is none), and the consent source. Check it and confirm with Import.

While the import runs, a progress line shows how many rows have been processed out of the file’s total. Large files upload in blocks, and the wait goes from seconds to minutes — the counter is what tells “still working” apart from “stuck”.

Caution

Don’t close the dialog or the tab while the import is running. The batch is recorded from the first step and closed when it finishes; interrupted midway, it is marked as failed and the rows already loaded stay in the directory. In that case, re-import the same file — repeated rows are rejected as duplicates, they don’t duplicate anyone.

Step 4 — Report

The report closes the wizard with two counts — accepted and rejected — and, below them, one line per rejection, giving the row number in the file, the contact, and the reason.

The rejection reasons

Reason	What happened
The row has no email	The email column was mapped, but the cell is empty
The row has neither email nor phone	No usable identifier on the row
The email is not a valid address	The address syntax is wrong
This email appears more than once in the file	Duplicate within the CSV itself; the first occurrence went in
This email’s domain doesn’t accept messages	The domain publishes no mail server
This address is on the organization’s suppression list	There was a hard bounce or a spam complaint
This person unsubscribed from the list	They only come back through the preference center, never by import
The phone already belongs to another contact	The number in the spreadsheet is someone else’s in the directory
This contact already has a different phone on file	The person was found by email and has a different number
The phone provided belongs to a contact with a different email	The person was found by phone and has another address

The last three are identity conflicts, and the wizard rejects the row on purpose. Changing someone’s phone number changes where their messages go; deciding whether two records are the same person is people’s work, not an import’s. Resolve it from the contact’s record under Contacts, then re-import if it still makes sense.

The unsubscribe and suppression reasons also apply to someone whose data was deleted from SquadOS: the protection against new sends is kept after the deletion, and importing the person again does not remove it.

After the import

Contacts that landed in a list fire the “Contact added to list” trigger, so automations wired to that list start running. If you’re about to import a large base into a list that already has an active automation, check what’s armed first under Automations.

To put contacts on a list from an external system — a form, a checkout, a CRM — instead of from a file, use the Contact Lists endpoints.