Skip to main content

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.

​
Overview

This guide walks you through importing relations between objects—for example, linking People to Companies, or Opportunities to People.
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.

​
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

Relation”One” Side (Parent)“Many” Side (Child)
Companies → PeopleCompanyPeople
Companies → OpportunitiesCompanyOpportunities
People → TasksPersonTasks
People → NotesPersonNotes

​
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)
If the parent record doesn’t exist, the import will fail.Always verify that Companies are imported before importing People with company references.

​
Step 3: Note the Parent’s Unique Identifier

You need to reference the parent record using a unique identifier. Available options:
Parent ObjectAvailable Unique Identifiers
Companiesid (UUID), domain (recommended), or any custom unique field
Peopleid (UUID), email, or any custom unique field
Workspace Membersid (UUID), email (not name)
Custom Objectsid (UUID), or any field marked as unique
Recommended: Use domain for Companies and email for People. These are human-readable and easy to verify in your spreadsheet.

​
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,john@acme.com,CEO,https://acme.com
Jane,Doe,jane@widgets.co,CTO,https://widgets.co
Bob,Johnson,bob@techstart.io,Developer,https://techstart.io
The companyDomain column references the Company’s domain.

​
Format Requirements

IdentifierFormatExample
DomainURL formathttps://acme.com
EmailStandard emailjohn@acme.com
IDUUIDc776ee49-f608-4a77-8cc8-6fe96ae1e43f
Domain format matters!Use https://domain.com (not just domain.com). This matches how Twenty stores Company domains and prevents matching errors.

​
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

MistakeProblemSolution
Wrong import orderImporting People before CompaniesAlways import parents first, then children
Wrong domain formatUsing acme.com instead of https://acme.comUse full URL format with https://
Multiple unique fieldsMapping both companyId AND companyDomainMap only ONE unique identifier
Missing relation fieldThe relation field doesn’t exist in the data modelCreate it in Settings → Data Model before importing
Non-existent recordsThe parent record doesn’t exist in TwentyImport parent records first, or check for typos
Case mismatchAcme.com in file but acme.com in TwentyEnsure exact case matching

​
Linking to Workspace Members

When linking to Workspace Members (your team):
  • Use their email address, not their name
  • Example: owner@yourcompany.com, not “John Smith”
taskName,assignedTo
Follow up with client,john@yourcompany.com
Review proposal,jane@yourcompany.com

​
FAQ

You have two options:
  1. Use the Twenty id (export parent records to get their IDs)
  2. Create a custom unique field in your data model to store an external ID from your previous system
Yes! Include the child record’s unique identifier (e.g., email for People) and the new relation value. The import will update the relation.
Many-to-Many relations are not yet supported for import. This is planned for H1 2026.
The import will show an error for that row. You can either:
  • Import the parent record first, then re-import
  • Fix the reference value
  • Remove the row from import
Common causes:
  • Wrong format (use https://domain.com for domains)
  • Case mismatch (check exact spelling)
  • Parent doesn’t exist (import parents first)
  • Mapping multiple identifiers (use only one)
Remember: Soft-deleted records count toward uniqueness.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.

​
Troubleshooting

Having issues? Check: