twenty/packages/twenty-docs/user-guide/data-migration/how-tos/prepare-your-csv-files.mdx

---
title: Prepare Your CSV Files
description: 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 |

<Note>For datasets larger than 10,000 records, split into multiple files or use the [API import](/user-guide/data-migration/how-tos/import-data-via-api).</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.

| 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

<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: `name@domain.com`
- Must be unique (no duplicates in file or in Twenty)
- For additional emails, use this format in the **Emails / Additional Emails** column:
```
["jane@twenty.com","jane.doe@twenty.com"]
```

### 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`

<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,john@acme.com,https://acme.com
Jane,Doe,jane@widgets.co,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)

<Warning>
**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.
</Warning>

See [How to Import Relations](/user-guide/data-migration/how-tos/import-relations-between-objects-via-csv) 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

| 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](/user-guide/data-migration/how-tos/import-companies-via-csv) (import these first)
- [Import Contacts](/user-guide/data-migration/how-tos/import-contacts-via-csv)
- [Fix any import errors](/user-guide/data-migration/how-tos/fix-import-errors)