Import Relations Between Objects via CSV

Overview

This guide walks you through importing relations between objects—for example, linking People to Companies, or Opportunities to People.

<Note>What can be imported: Only one-to-many relations pointing to a single object type. Relations pointing to multiple object types (like Notes linking to People AND Companies) are not yet supported for import.</Note>

Understanding Relations

What is a "One-to-Many" Relation?

In a one-to-many relation:

• One Company has many People (employees)
• One Company has many Opportunities
• One Person has many Tasks

The "one" side is the parent. The "many" side is the child.

Common Relations in Twenty

Step 1: Identify the "One" and "Many" Sides

Before importing, determine which object is the parent and which is the child.

Ask yourself: "Does ONE [Object A] have MANY [Object B]?"

• One Company → Many People ✓ (Company is parent)
• One Person → Many Companies ✗ (This is wrong—a person belongs to one company)

Step 2: Import the Parent Records First

The parent ("one" side) must exist in Twenty before you can reference it.

Import order:

1. Companies first (no dependencies)
2. People second (link to Companies)
3. Opportunities third (link to Companies and/or People)
4. Tasks/Notes (link to any of the above)

Always verify that Companies are imported before importing People with company references. </Warning>

Step 3: Note the Parent's Unique Identifier

You need to reference the parent record using a unique identifier. Available options:

<Note>Recommended: Use domain for Companies and email for People. These are human-readable and easy to verify in your spreadsheet.</Note>

Finding the Identifier

If you need the id:

1. Export the parent records from Twenty
2. The export includes the id column
3. Use these IDs in your child records file

Step 4: Verify the Relation Field Exists

Before importing, ensure the relation field exists between your objects.

To check or create:

1. Go to Settings → Data Model
2. Select your child object (e.g., People)
3. Look for a relation field pointing to the parent (e.g., Company)
4. If it doesn't exist, create it:
   • Click + Add field
   • Select Relation type
   • Choose the parent object

Step 5: Prepare Your CSV File

Add a column to your child CSV that references the parent using its unique identifier.

Example: People Linking to Companies

Your People CSV:

firstName,lastName,email,jobTitle,companyDomain
John,Smith,[email protected],CEO,https://acme.com
Jane,Doe,[email protected],CTO,https://widgets.co
Bob,Johnson,[email protected],Developer,https://techstart.io

The companyDomain column references the Company's domain.

Format Requirements

Use https://domain.com (not just domain.com). This matches how Twenty stores Company domains and prevents matching errors. </Warning>

Important Rules

1. Exact match required — the value must exactly match the parent record
2. Map only ONE unique identifier — don't include both companyId AND companyDomain
3. Case sensitive — Acme.com ≠ acme.com

Step 6: Upload and Map the Relation

1. Navigate to the child object (e.g., People)
2. Click ⋮ → Import records
3. Upload your CSV file
4. In the field mapping step:
   • Find your relation column (e.g., companyDomain)
   • Map it to the Company relation field
5. Complete the remaining mapping
6. Review errors and confirm

Twenty will automatically link each child record to the matching parent.

Step 7: Verify the Import

After importing:

1. Open a few child records (e.g., People)
2. Verify the relation field shows the correct parent (e.g., Company)
3. Open a parent record and check the related records section

Common Mistakes to Avoid

Linking to Workspace Members

When linking to Workspace Members (your team):

• Use their email address, not their name
• Example: [email protected], not "John Smith"

taskName,assignedTo
Follow up with client,[email protected]
Review proposal,[email protected]

FAQ

If you're getting "not found" errors but the record seems to exist, check Command Menu → See deleted records. The parent may have been soft-deleted. </Warning>

Troubleshooting

Having issues? Check:

• How to Fix Import Errors
• Import Relations Capabilities
• Uniqueness Constraints