Import Relations Between Objects

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, Tasks, or Activities 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.

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.

• 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 H1 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,[email protected],https://acme.com
Jane,Doe,[email protected],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

<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 for more details.</Note>

Import Order Rule

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>