Import Contacts via CSV

Overview

This guide walks you through importing your contacts (People) into Twenty. Import Companies first if you want to link People to Companies.

Before You Start

Prerequisites Checklist

If you want to link People to Companies, import Companies first. The Company must exist before you can reference it. </Warning>

Step 1: Prepare Your Contact Data

Required and Recommended Fields

Email Format

• Must be valid email format: [email protected]
• Must be unique — no duplicates in your file or in Twenty
• For additional emails, use the Emails / Additional Emails column:

["[email protected]","[email protected]"]

Phone Format

Phone is a nested field requiring multiple columns:

Linking to Companies

Add a column with the Company's unique identifier:

Sample CSV Structure

firstName,lastName,email,jobTitle,companyDomain,Phones / Primary Phone Number,Phones / Primary Phone Country Code
John,Smith,[email protected],CEO,https://acme.com,4159095555,US
Jane,Doe,[email protected],CTO,https://widgets.co,2125551234,US

Step 2: Access the Import Feature

Option 1: From the People View

1. Navigate to People in the left sidebar
2. Click the ⋮ icon on the top right
3. Select Import records

Option 2: Using Command Menu

1. Press Cmd + K (Mac) or Ctrl + K (Windows)
2. Type "import"
3. Select Import records
4. Choose People

Step 3: Upload Your File

1. Click Select file
2. Choose your CSV, XLSX, or XLS file
3. Wait for Twenty to analyze your file

Step 4: Map Your Columns

Twenty automatically tries to match your columns to fields. Review and adjust:

1. Check automatic mappings — verify they're correct
2. Fix incorrect mappings — click the dropdown to select the right field
3. Skip columns — select Do not map for columns you don't want to import

Important Mapping Rules

Mapping the Company Relation

When mapping the company column:

1. Find your company reference column (e.g., companyDomain)
2. Map it to the Company relation field
3. Twenty will link each Person to the matching Company

Don't map both companyId AND companyDomain. Choose one—preferably domain since it's human-readable. </Warning>

Step 5: Map Select Field Values

If you have Select or Multi-Select fields (like Lead Source):

1. Twenty shows your values alongside existing options
2. Match each value in your file to a Twenty option
3. Or create new options if needed

Step 6: Review and Fix Errors

Before completing the import, Twenty validates your data:

1. Click Next Steps
2. Rows with errors are highlighted in yellow
3. Fix errors directly — click a cell and edit the value
4. Remove problematic rows — click the X to skip that row

Common Contact Import Errors

Step 7: Complete the Import

1. Review the import summary
2. Click Confirm to import
3. Wait for the import to complete
4. Verify by checking a few records and their Company links

After Importing Contacts

Your contacts are now in Twenty! Next steps:

1. Verify Company links — open a few People records to confirm they're linked to the right Company
2. Import Opportunities — if needed, link them to People and Companies
3. Set up email sync — connect your mailbox to see email history on contact records

Updating Existing Contacts

To update contacts instead of creating new ones:

1. Include the email or id column in your file
2. Twenty matches records by this unique identifier
3. Existing contacts are updated; new ones are created

See How to Update Existing Records for details.

FAQ

Troubleshooting

Having issues? Check:

• How to Fix Import Errors
• How to Import Relations
• Field Mapping Reference