Passer au contenu principal

​
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:
RequirementDetails
FormatCSV, XLSX, or XLS
Size limit10,000 records per file
EncodingUTF-8 recommended
StructureOne 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.
ObjectUnique Fields
Peopleid, email
Companiesid, domain
Custom objectsid, 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: [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:
ColumnExample
Phones / Primary Phone Number4159095555
Phones / Primary Phone Country CodeUS
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
  • MM/DD/YYYY: 03/15/2024
  • DD/MM/YYYY: 15/03/2024
  • 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:
ColumnExample
Amount / Amount1234.56
Amount / CurrencyUSD

​
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,[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 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

MistakeSolution
Using true instead of TRUEBoolean values must be uppercase
Using display labels for Select fieldsFind and use API names in Settings
Importing People before CompaniesAlways import parent objects first
Missing currency code for Currency fieldsFill both Amount and Currency columns
Wrong domain formatUse https://domain.com consistently
Mapping multiple unique fields for relationsMap only ONE (domain OR id, not both)

​
Next Steps

Your file is ready! Now: