snapshot of https://github.com/twentyhq/twenty.git (main, 2026-09-17; blobs > 131072B omitted)

packages/twenty-docs/user-guide/data-migration/capabilities/error-handling.mdx

@@ -0,0 +1,70 @@
+---
+title: Error Handling & Validation
+description: Review and fix import errors directly in the UI before confirming.
+---
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## Pre-Import Validation
+
+After uploading your file and mapping fields, Twenty validates your data **before** importing. This allows you to catch and fix errors without affecting your existing data.
+
+## How It Works
+
+1. **Upload** your CSV file
+2. **Map** your columns to Twenty fields
+3. **Review** the potential errors highlighted in yellow
+4. **Fix errors** directly in the UI
+5. **Confirm** the import
+
+<VimeoEmbed videoId="1145273857" title="Video demonstration" />
+
+
+## Error Display
+
+Rows with issues are highlighted in **yellow**. You can:
+- **Edit the cell directly** to fix the error
+- **Remove the row** to skip it entirely
+
+This inline editing saves time — no need to go back to your spreadsheet, fix errors, and re-upload.
+
+## Common Error Types
+
+### Duplicate Values
+**Cause**: A unique field (email, domain) already exists in Twenty or appears twice in your file.
+
+**Fix**:
+- Edit the duplicate value in the import UI
+- Remove one of the duplicate rows
+
+See [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) for more details on how uniqueness is enforced.
+
+### Invalid Format
+**Cause**: Data doesn't match the expected format (e.g., invalid email, wrong date format).
+
+**Fix**: Edit the cell to use the correct format.
+
+See [Field Mapping](/user-guide/data-migration/capabilities/field-mapping) for the expected format of each field type.
+
+### Missing Required Fields
+**Cause**: A required field is empty.
+
+**Fix**: Enter a value in the required field or remove the row.
+
+### Relation Not Found
+**Cause**: The referenced record doesn't exist (e.g., a Company domain that wasn't imported).
+
+**Fix**:
+- Import the parent records first
+- Or correct the reference value
+
+See [Import Relations](/user-guide/data-migration/capabilities/import-relations) for the correct import order and how to link records.
+
+## Tips for Fewer Errors
+
+1. **Download the template** to see the expected format prior to importing your file
+2. **Clean your data** in the spreadsheet first
+3. **Import files in correct order** to import relations (Companies → People → Opportunities)
+4. **Test with small batches** before full import
+5. **Check for duplicates** before uploading
+6. **Limit each file to 10,000 records**
+

packages/twenty-docs/user-guide/data-migration/capabilities/field-mapping.mdx

@@ -0,0 +1,164 @@
+---
+title: Field Mapping
+description: How field mapping works during data import.
+---
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## How Field Mapping Works
+
+When you upload a file, Twenty analyzes your columns and attempts to match them to existing fields.
+
+### Automatic Mapping
+Twenty tries to match columns based on:
+- Column header names (exact or similar matches)
+- Data type detection (dates, numbers, emails)
+- Common field patterns
+
+<Note>**Quick tip:** Export a few rows from the object you want to import. The exported file will have the exact column names Twenty expects, making automatic mapping seamless during import.</Note>
+
+### Manual Mapping Options
+For each column, you can:
+- **Map to a field**: Select the matching Twenty field from a dropdown
+- **Do not map**: Skip the column entirely (data won't be imported)
+
+<Note>**Fields must exist before import.** The import creates records, not fields. Create custom fields under **Settings → Data Model** before importing.</Note>
+
+## Field Type Compatibility
+
+All field types available in the Data Model are supported for import.
+
+You can also import `id` values to either assign a specific ID to new records or update existing ones.
+
+<img src="/images/user-guide/fields/all-field-types.png" style={{width:'100%'}}/>
+
+## Data Format Requirements
+
+<Note>**Some fields have special syntax.** We recommend downloading the sample file before preparing your import to see the expected syntax for each field type.</Note>
+
+### 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
+- **Address / City**: City name
+- **Address / State**: State or province
+- **Address / Country**: Country name
+- **Address / Post Code**: Postal/ZIP code
+
+### Array Fields
+Use the following format:
+```
+["value1","value2"]
+```
+
+### Boolean Fields
+Use `TRUE` or `FALSE` (uppercase) - not `true` or `false`
+
+### Currency Fields
+Currency is a nested field with two columns that **both must be filled**:
+- **Amount / Amount**: The numeric value (e.g., `1234.56`)
+- **Amount / Currency**: The currency code (e.g., `USD`, `EUR`)
+
+### Date Fields
+Supported formats:
+- `YYYY-MM-DD` (recommended)
+- `MM/DD/YYYY`
+- `DD/MM/YYYY`
+- ISO 8601 format
+
+### Domain Fields
+- It is recommended to use the format `https://domain.com` to avoid creating duplicates, as this is the format used for Companies created by the mailbox and calendar synchronizations
+- A `Domain Label` and `Domain URL` can be filled: best practice is to fill `domain.com` in the label and `https://domain.com` in the url
+- Domains must be unique within the Companies object
+- **Domains must be unique within the file to import**
+
+### Email Fields
+- Must be valid email format
+- Emails must be unique within the People object
+- **Emails must be unique within the file to import**
+- For additional emails: use **Emails / Primary Email** for the main email, and **Emails / Additional Emails** with this format:
+```
+["jane@twenty.com","jane.doe@twenty.com"]
+```
+
+### ID Fields
+Specifying an `id` during import is optional. Twenty auto-generates one if not provided.
+
+Use cases for mapping an `id` column:
+- **Set a specific ID**: Choose the UUID for newly created records
+- **Update existing records**: Match against existing records to update them instead of creating duplicates. In that case, it is recommended to not map the other unique fields: mapping only one unique field ensures a smoother import.
+
+<Note>If you provide an `id`, it must be in UUID format (e.g., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
+
+
+### JSON Fields
+Use valid JSON format:
+```
+{"key":"value","key2":"value2"}
+```
+
+### Links Fields
+Similar to Domain fields:
+- Fill both the label and URL columns: **Links / Link URL** and **Links / Link Label**
+- Use full URL format: `https://example.com`
+- For secondary links, use **Links / Secondary Links** column with this format:
+```
+[{"url":"https://twenty.com","label":"Twenty"}]
+```
+
+### Multi-Select Fields
+Use the **API names** (not the display labels) in the following format:
+```
+["VALUE1","VALUE2"]
+```
+See [here](#finding-api-names-for-select-fields) where to find the API names.
+
+<Note>New select options will not be created automatically by the import. They must be added under **Settings → Data Model** before importing.</Note>
+
+<Warning>
+**Import overwrites; it does not add.**
+
+If a record already has `VALUE2` and `VALUE3` selected, and you import `["VALUE1"]`, the record will only have `VALUE1` after import. The previous selections are replaced, not merged.
+</Warning>
+
+
+### Number Fields
+- Numbers only
+- Decimals use period: `1234.56`
+- No thousands separators
+
+### Phone Fields
+Phone is a nested field with multiple columns that **must be filled**
+- **Phones / Primary Phone Number**: The phone number (e.g., `4159095555`)
+- **Phones / Primary Phone Country Code**: Country code (e.g., `US`)
+- **Phones / Primary Phone Calling Code**: Dialing code (e.g., `+1`)
+
+### Rating Fields
+Use the API name format: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, `RATING_5`
+
+### Relation Fields
+Please see our dedicated article: [Import Relations Between Objects](/user-guide/data-migration/capabilities/import-relations)
+
+### Select Fields
+Use the **API name** of the option (not the display label):
+```
+VALUE1
+```
+See [here](#finding-api-names-for-select-fields) where to find the API names.
+<Note>New select options will not be created automatically by the import. They must be added under **Settings → Data Model** before importing.</Note>
+### Text Fields
+- No special formatting required
+- Leading/trailing spaces are trimmed
+
+## Finding API Names
+
+For Select, Multi-Select, and Array fields with predefined options, you must use the **API names**, not the display labels.
+
+### How to Find API Names
+1. Go to **Settings → Data Model**
+2. Select the object and field
+3. Enable **Advanced mode** (toggle at the bottom right of the settings page)
+4. View the API name for each option
+
+<VimeoEmbed videoId="1144910809" title="Video demonstration" />
+
+

packages/twenty-docs/user-guide/data-migration/capabilities/file-formats.mdx

@@ -0,0 +1,47 @@
+---
+title: Supported File Formats
+description: File formats supported for data import in Twenty.
+---
+
+## Supported Formats
+
+Twenty supports three file formats for import:
+
+| Format | Extension | Notes |
+|--------|-----------|-------|
+| **CSV** | .csv | Recommended, most compatible |
+| **Excel** | .xlsx | Modern Excel format |
+| **Excel (Legacy)** | .xls | Older Excel format |
+
+## File Requirements
+
+| Requirement | Value |
+|-------------|-------|
+| **Encoding** | UTF-8 recommended |
+| **Record limit** | 10,000 records per file |
+| **Structure** | First row must contain column headers |
+| **Content** | One object type per file |
+
+## CSV Best Practices
+
+- **Delimiter**: Use comma (`,`) or semicolon (`;`)
+- **Text qualifier**: Use double quotes (`"`) for text containing commas
+- **Line endings**: Windows (CRLF) or Unix (LF) both supported
+- **Empty values**: Leave cells empty, don't use "NULL" or "N/A"
+
+## Excel Best Practices
+
+When exporting from Excel:
+- Remove formulas (export values only)
+- Delete empty rows at the end
+- Ensure no merged cells
+- Use the first sheet only
+
+## Large Datasets
+
+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) for unlimited records
+
+<Note>For very large migrations (100,000+ records), the API is significantly faster and more reliable than CSV imports.</Note>
+

packages/twenty-docs/user-guide/data-migration/capabilities/import-relations.mdx

@@ -0,0 +1,141 @@
+---
+title: Import Relations Between Objects
+description: Import relationships between records via CSV.
+---
+
+## Overview
+
+Twenty supports importing relationships between objects during CSV import. This allows you to link records (e.g., attach People to Companies) as part of your data migration.
+
+<Note>**Currently supported for import**: One-to-many relations pointing to a single object type on each side (e.g., People → Companies). Relations pointing to multiple object types are not yet supported in import/export.</Note>
+
+## How Relations Work in Twenty
+
+### One to Many / Many to One
+
+Twenty supports standard relations where one record links to many others:
+
+- **One Company → Many People**: A company can have multiple employees, but each person belongs to one company
+- **One Company → Many Opportunities**: A company can have multiple deals, but each opportunity belongs to one company
+
+### Relations That Can Point to Multiple Object Types
+
+Some relations can connect to different types of objects. This works in two ways:
+
+**Pattern 1: Many records linking to one record each from different object types**
+
+Several Notes or Tasks can each be attached to multiple object types at once:
+- **Notes** can be linked to one Person, one Company, and one Opportunity simultaneously
+- **Tasks** can be linked to one Person, one Company, and one Opportunity simultaneously
+
+Here, the Notes/Tasks are on the "many" side. Each links to one record per object type.
+<img src="/images/user-guide/fields/many-to-one-morph.png" style={{width:'100%'}}/>
+
+
+**Pattern 2: One record receiving links from many records of different object types**
+
+A Project can receive links from multiple records across different object types:
+- **A Project** can have many People linked to it, many Companies linked to it, and many Notes attached to it
+
+Here, the Project is on the "one" side. Multiple records from different objects can all link to the same Project.
+<img src="/images/user-guide/fields/one-to-many-morph.png" style={{width:'100%'}}/>
+
+<Warning>
+**Import/Export limitation**: Relations that point to multiple object types (like Notes → People/Companies/Opportunities) are **not yet supported** in CSV import or export.
+
+- **Import**: Only one-to-many relations pointing to a single object type on each side can be imported
+- **Export**: Columns for relations pointing to multiple object types are currently left empty
+
+This is on our roadmap.
+</Warning>
+
+
+### What's Not Supported Today
+
+**Many to Many relations** are not yet available. For example, you cannot currently create a relation where:
+- Many People are linked to many Projects
+
+<Note>Many to Many relations are planned for H2 2026.</Note>
+
+## Linking Records During Import
+
+<Note>**Reminder**: Only one-to-many relations pointing to a single object type can be imported (e.g., People → Companies). Relations pointing to multiple object types (e.g., Notes → People/Companies/Opportunities) are not yet supported.</Note>
+
+### Step 1: Identify the "One" and "Many" Sides
+
+First, determine which object is on the "one" side and which is on the "many" side of the relationship.
+
+**Example**:
+- **Company** is the "one" side (one company has many employees)
+- **People** is the "many" side (each person belongs to one company)
+
+### Step 2: Ensure the "One" Side Records Exist
+
+Before importing the "many" side, the "one" side records must already exist in Twenty.
+
+- Import or create the "one" side records first (e.g., Companies)
+- Validate their unique identifier. This can be:
+  - The `id` (Twenty's UUID)
+  - A field set as unique (e.g., `domain` for Companies, or an external ID from your previous system)
+
+<Warning>The import will fail if a reference is made to a record that does not exist.</Warning>
+
+### Step 3: Prepare Your CSV File
+
+Add a column in your "many" side CSV file that references the "one" side record.
+
+**Example**: For a People CSV file linking to Companies:
+```
+firstName,lastName,email,companyDomain
+John,Smith,john@acme.com,https://acme.com
+Jane,Doe,jane@widgets.co,https://widgets.co
+```
+
+**Important**:
+- The value must **exactly match** the unique field on the Company record
+- For domains, use the **Domain URL** (e.g., `https://acme.com`), not the Domain Label
+- Map only **one** unique identifier per relation: this leads to a smoother import
+
+### Step 4: Ensure the Relation Field Exists
+
+Before uploading your file, make sure the relation field exists between your objects.
+
+If it doesn't exist:
+1. Go to **Settings → Data Model**
+2. Select your object (e.g., People)
+3. Create a relation field pointing to the target object (e.g., Company)
+
+### Step 5: Upload and Map the Relation
+
+1. Upload your CSV file via the import UI
+2. In the field mapping step, find your relation column (e.g., `companyDomain`)
+3. Map it to the relation field (e.g., Company)
+4. Twenty will automatically link each record to the matching parent
+
+### Available Unique Fields for Relations
+
+| Object | Unique Fields Available |
+|--------|------------------------|
+| **Companies** | `id`, `domain`, any custom unique field |
+| **People** | `id`, `email`, any custom unique field |
+| **Workspace Members** | `id`, `email` (not name) |
+| **Other standard and custom objects** | `id`, any field marked as unique |
+
+<Note>**Linking to Workspace Members**: When the relation points to Workspace Members (your team logging into Twenty), reference them by their **email address**, not their name.</Note>
+
+<Note>We recommend using `domain` for Companies and `email` for People, as these are human-readable and easy to maintain in spreadsheets.</Note>
+
+<Note>**Reminder**: Soft-deleted records (visible under Command Menu → See deleted records) count toward uniqueness criteria. If you import a record with the same unique value as a deleted record, the deleted record will be restored. See [Uniqueness Constraints](/user-guide/data-migration/capabilities/uniqueness-constraints) for more details.</Note>
+
+## Import Order Rule
+
+<Warning>
+**Always import the "one" side first!**
+
+1. **Companies** first (no dependencies)
+2. **People** second (linked to Companies)
+3. **Opportunities** third (linked to Companies/People)
+4. **Custom objects** following their dependencies
+
+The parent record must exist before you can reference it.
+</Warning>

packages/twenty-docs/user-guide/data-migration/capabilities/uniqueness-constraints.mdx

@@ -0,0 +1,68 @@
+---
+title: Uniqueness Constraints
+description: How Twenty enforces data uniqueness during import.
+---
+import { VimeoEmbed } from '/snippets/vimeo-embed.mdx';
+
+## Overview
+
+Twenty enforces uniqueness on certain fields to prevent duplicate records and ensure data integrity. Understanding these constraints is essential for successful imports.
+
+## Default Unique Fields
+
+| Object | Unique Fields |
+|--------|---------------|
+| **People** | `id`, `email` |
+| **Companies** | `id`, `domain` |
+| **Custom objects** | `id` only (by default) |
+
+<Note>The `id` field is Twenty's internal identifier, auto-generated for each record. It uses UUID format (e.g., `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>
+
+## Custom Unique Fields
+
+You can define additional unique fields under **Settings → Data Model**:
+
+1. Go to **Settings → Data Model**
+2. Select the object
+3. Click on a field
+4. Enable **Unique** in field settings
+
+### Use Cases for Custom Unique Fields
+- **External IDs**: Store IDs from other systems (Salesforce ID, HubSpot ID)
+- **Business identifiers**: Employee numbers, customer codes
+- **Alternative contact info**: LinkedIn profile, phone number
+
+<Note>The field name `id` is reserved for Twenty's internal ID. Use a different name like `externalId` or `legacyId` for external identifiers.</Note>
+
+## Import Behavior
+
+### Creating New Records
+If a unique field value doesn't exist, a new record is created.
+
+### Updating Existing Records
+If a unique field value matches an existing record, that record is **updated** with the new data.
+<Warning>To **update existing records**, it is recommended to **only match one unique field**.</Warning>
+
+### Soft-Deleted Records
+
+<Warning>
+**Deleted records count toward uniqueness.**
+
+Soft-deleted records (visible under Command Menu → See deleted records) are included in uniqueness checks. If you import a record with the same unique value as a deleted record, the deleted record will be **restored** with the new data.
+</Warning>
+
+## Duplicate Detection During Import
+
+During the validation phase:
+- Duplicates within your file are highlighted in yellow
+- You can edit or remove duplicate rows from the UI before starting the import
+
+<VimeoEmbed videoId="1145246326" title="Video demonstration" />
+
+## Best Practices
+
+1. **Remove duplicates** from your file before importing
+2. **Check for existing records** in Twenty before importing
+3. **Use external IDs** when migrating from other systems
+4. **Include unique fields** if you want to update existing records
+