Prepare Your CSV Files

Overview

This guide walks you through preparing your CSV file for a successful import. Follow these steps in order to avoid errors.

Step 1: Check File Requirements

Before you start, ensure your file meets these requirements:

<Note>For datasets larger than 10,000 records, split into multiple files or use the API import.</Note>

Step 2: Download the Sample File

This is the most important step. The sample file shows you the exact column names and format Twenty expects.

1. Go to the object view (People, Companies, etc.)
2. Click ⋮ → Import records
3. Click Download sample file
4. Use this file as your template

<Note>Pro tip: Export a few existing records instead. This gives you real examples of how data should be formatted, and the column names will map automatically during import.</Note>

Step 3: Remove Duplicate Values

Twenty enforces uniqueness on certain fields. Duplicates will cause import errors.

Before importing:

1. Sort your spreadsheet by the unique field (email or domain)
2. Remove or merge duplicate rows
3. Check for duplicates that already exist in Twenty

<Warning>Soft-deleted records count toward uniqueness. Records in Command Menu → See deleted records will cause duplicate errors. Delete them permanently or restore and update them.</Warning>

Step 4: Format Each Field Type Correctly

Different field types require specific formats. Here's the complete reference:

Text Fields

• No special formatting required
• Leading/trailing spaces are automatically trimmed

Email Fields

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

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

Domain Fields

• Recommended format: https://domain.com
• This matches the format used by mailbox/calendar sync (prevents duplicates)
• Fill both columns:
  • Domain / Domain Label: domain.com
  • Domain / Domain URL: https://domain.com
• Must be unique within your file and in Twenty

Phone Fields

Phone is a nested field requiring multiple columns:

Address Fields

Address is a nested field with multiple columns (some can be left empty):

• Address / Address 1: Street address line 1
• Address / Address 2: Street address line 2 (optional)
• Address / City: City name
• Address / State: State or province
• Address / Country: Country name
• Address / Post Code: Postal/ZIP code

Date Fields

Use consistent formatting throughout your file:

• YYYY-MM-DD (recommended): 2024-03-15
• ISO 8601: 2024-03-15T10:30:00Z

Number Fields

• Numbers only (no text)
• Use period for decimals: 1234.56
• No thousands separators (not 1,234.56)

Currency Fields

Currency is a nested field requiring two columns that both must be filled:

Boolean Fields

Use uppercase: TRUE or FALSE

<Warning>Lowercase true or false will not work.</Warning>

Select Fields

Use the API name of the option, not the display label.

How to find API names:

1. Go to Settings → Data Model
2. Select the object and field
3. Enable Advanced mode (toggle at bottom right)
4. Copy the API name (e.g., OPTION_1, not "Option 1")

<Note>New select options are not created automatically. Add them in Settings → Data Model before importing.</Note>

Multi-Select Fields

Use API names in array format:

["VALUE1","VALUE2"]

Array Fields

Use JSON array format:

["value1","value2"]

Rating Fields

Use the format: RATING_1, RATING_2, RATING_3, RATING_4, or RATING_5

Links/URL Fields

Fill both columns:

• Links / Link Label: Twenty
• Links / Link URL: https://twenty.com

For secondary links, use the Links / Secondary Links column:

[{"url":"https://twenty.com","label":"Twenty"}]

JSON Fields

Use valid JSON format:

{"key":"value","key2":"value2"}

ID Fields

• Optional: Twenty auto-generates IDs if not provided
• Format: UUID (e.g., c776ee49-f608-4a77-8cc8-6fe96ae1e43f)
• Use case: Include ID to update existing records instead of creating new ones

Step 5: Add Relation Columns (If Linking Records)

To link records to other objects (e.g., People to Companies), add a column with the unique identifier of the related record.

Example: Linking People to Companies

Add a column to your People CSV:

firstName,lastName,email,companyDomain
John,Smith,[email protected],https://acme.com
Jane,Doe,[email protected],https://widgets.co

Important rules for relations:

• The parent record must already exist in Twenty
• Use the Domain URL format (https://domain.com), not the label
• Map only ONE unique identifier (don't include both companyId AND companyDomain)
• For Workspace Members, use their email (not name)

Import the "one" side before the "many" side:

1. Companies first
2. People second (with company reference)
3. Opportunities third

The parent record must exist before you can reference it. </Warning>

See How to Import Relations for detailed instructions.

Step 6: Ensure Fields Exist in Twenty

The import creates records, not fields. All fields you want to import must already exist in your data model.

Before importing:

1. Go to Settings → Data Model
2. Select your object
3. Create any custom fields you need
4. Note the exact field names (they must match your column headers)

Step 7: Final Checklist

Before uploading your file, verify:

<Check>File is CSV, XLSX, or XLS format</Check> <Check>File has fewer than 10,000 records</Check> <Check>Encoding is UTF-8</Check> <Check>No duplicate emails (for People) or domains (for Companies)</Check> <Check>Dates use consistent format throughout</Check> <Check>Domains use https://domain.com format</Check> <Check>Boolean fields use TRUE or FALSE (uppercase)</Check> <Check>Select fields use API names, not display labels</Check> <Check>All custom fields exist in Settings → Data Model</Check> <Check>Parent records imported before child records</Check> <Check>Relation columns reference existing records</Check>

Common Mistakes to Avoid

Next Steps

Your file is ready! Now:

• Import Companies (import these first)
• Import Contacts
• Fix any import errors