CSV Import (Advanced Guide)
Detailed guide for importing prospects via CSV:
Supported Columns:
- email (required unless linkedinUrl is provided)
- firstName, lastName, company, role (job title)
- website, phone, linkedinUrl
- country, city, industry
- Custom fields: use prefix custom: (e.g., custom:department, custom:source)
Auto Column Mapping:
The system automatically maps common column name variations:
• 'e-mail', 'e_mail' → email
• 'first name', 'first_name' → firstName
• 'last name', 'last_name' → lastName
• 'company name', 'company_name' → company
• 'title', 'job_title', 'position' → role
• 'telephone', 'mobile' → phone
• 'linkedin', 'linkedin_url', 'linkedin_profile' → linkedinUrl
You can also manually map any column during the import wizard.
Validation & Deduplication:
- Email format validation (must be valid format)
- MX DNS validation (domain must have valid mail server)
- Dedup by email within the file and against existing workspace prospects
- LinkedIn URL dedup for LinkedIn-only rows
- Suppression list check (both email-level and domain-level)
LinkedIn-Only Rows:
If a row has no valid email but has a LinkedIn URL, a placeholder email ([email protected]) is generated so the prospect can exist in the system.
Custom Fields:
Any CSV column not matching a built-in field is stored as a custom field. Field names are sanitized: lowercased, non-alphanumeric characters replaced with underscores, max 30 characters.
Re-Uploading to Add or Update Custom Fields:
You can upload the same contacts again later to fill in or refresh their custom fields — you don't have to get every column right the first time.
• Contacts are matched by email address. When a match is found, the custom fields from your new file are ADDED to that existing contact, and changed values are updated. Nothing you imported before is lost.
• A blank cell never wipes an existing value. If your new file leaves a column empty for a contact who already has a value there, the existing value is kept — only real, filled-in values are written.
• Those matched contacts are also added to the list you're importing into, so if you're building a list, it ends up complete (both the brand-new people and the ones already in your account).
• Practical fix: if you added a personalized column (say custom:first_line) after your first import and it didn't appear, just upload the list one more time with that column filled in. It fills in on the existing contacts and they join the target list.
What a Re-Upload Will NOT Change (Built-In Fields Are Fill-Only):
Re-uploading updates your custom columns, but it treats built-in contact fields differently — and this catches people out, so it's worth knowing up front.
• Built-in fields (firstName, lastName, company, role, phone, website, country, city, industry) are only filled in when they are currently EMPTY on that contact. If a contact already has a first name, re-uploading a file with a different first name will NOT change it.
• This is deliberate: it means an import can never quietly overwrite a name or company you corrected by hand, and a messy export can't undo your cleanup.
• The trade-off: fixing a name by re-uploading a spreadsheet does not work. If you re-upload with corrected names (for example changing 'J. Guilherme' to 'Dr. João Guilherme') and nothing appears to happen, this is why — the existing value wins, and the import isn't broken.
• To change a built-in field on a contact you already have: edit the contact directly on the Contacts page. To rebuild from scratch: delete the contacts first, then re-import.
• Custom columns are the exception — those DO update on re-upload, which is why personalization columns are the right place for data you expect to refresh.
Using Custom Columns as Merge Tags:
Every custom column you import becomes a merge tag you can use in your campaign emails — including in the subject line. For example, a column custom:icebreaker becomes {{custom.icebreaker}} or {{icebreaker}} in your templates. This lets you send fully pre-written, personalized emails where every part is unique per prospect.
Import Progress:
- Large imports run asynchronously — you can close the page and come back
- Progress bar shows processed rows, created, duplicates, invalid, and suppressed counts
- Maximum 10,000 rows per import
Example CSV:
email,firstName,lastName,company,role,phone,linkedinUrl,website,country,city,industry,custom:department
[email protected],John,Smith,Acme Corp,VP Sales,+1234567890,linkedin.com/in/johnsmith,acme.com,US,New York,Technology,Engineering