Prepare Your CSV Files

Complete step-by-step guide to format your data for import into Twenty.

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:

Requirement	Details
Format	CSV, XLSX, or XLS
Size limit	10,000 records per file
Encoding	UTF-8 recommended
Structure	One object type per file

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

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

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.

Step 3: Remove Duplicate Values

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

Object	Unique Fields
People	id, email
Companies	id, domain
Custom objects	id, plus any field you marked as unique

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

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.

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: [e-mail]
• Must be unique (no duplicates in file or in Twenty)
• For additional emails, use this format in the Emails / Additional Emails column:

["[e-mail]","[e-mail]"]

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:

Column	Example
Phones / Primary Phone Number	4159095555
Phones / Primary Phone Country Code	US
Phones / Primary Phone Calling Code	+1

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:

Column	Example
Amount / Amount	1234.56
Amount / Currency	USD

Boolean Fields

Use uppercase: TRUE or FALSE

Lowercase true or false will not work.

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”)

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

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,[e-mail],https://acme.com
Jane,Doe,[e-mail],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 Order Matters!

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.

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:

File is CSV, XLSX, or XLS format

File has fewer than 10,000 records

Encoding is UTF-8

No duplicate emails (for People) or domains (for Companies)

Dates use consistent format throughout

Domains use https://domain.com format

Boolean fields use TRUE or FALSE (uppercase)

Select fields use API names, not display labels

All custom fields exist in Settings → Data Model

Parent records imported before child records

Relation columns reference existing records

Common Mistakes to Avoid

Mistake	Solution
Using true instead of TRUE	Boolean values must be uppercase
Using display labels for Select fields	Find and use API names in Settings
Importing People before Companies	Always import parent objects first
Missing currency code for Currency fields	Fill both Amount and Currency columns
Wrong domain format	Use https://domain.com consistently
Mapping multiple unique fields for relations	Map only ONE (domain OR id, not both)

Next Steps

Your file is ready! Now:

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