> ## Documentation Index
> Fetch the complete documentation index at: https://docs.twenty.com/llms.txt
> Use this file to discover all available pages before exploring further.

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

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