The Twenty CRM migration guide
Why teams migrate to Twenty CRM
The four shapes a Twenty CRM migration takes, and what makes the platform easier — or harder — than the category average.
Twenty was founded by Charles Bochet and Félix Malfait, launched publicly through Y Combinator (S23), and ships under an AGPL-3.0 licence with a self-hostable codebase on GitHub112. The team positions Twenty as a modern, open-source alternative to Salesforce and HubSpot — built from a clean slate in TypeScript, NestJS, React and PostgreSQL.
The typical Twenty customer is a developer-led startup, a SaaS company, or a small-to-mid-market team — 5 to 100 users — that wants Salesforce-depth customisation without the licensing cost, or a team replacing Zoho or HubSpot to escape contact-tier billing and vendor lock-in. Compared with Salesforce, Twenty positions on no governor limits, no per-seat licence and a metadata-driven data model that lets you build custom objects the same way the platform builds standard ones.
The shapes of migration that actually land on Twenty tend to fall into four patterns. First, Salesforce or HubSpot exits, driven by total cost of ownership and a desire for data ownership — practitioners cite $9/user Cloud or $0 licensing for self-host versus $25–$165/user/month on legacy CRMs. Second, Zoho consolidations, where a small team has hit reliability or customisation limits and wants a cleaner data model28.
Third, homegrown or vibe-coded CRM replacements — teams that built something in Lovable, Airtable or Notion and have outgrown it, but still want full control over the schema29. Fourth, self-hosted CRM moves from EspoCRM, SuiteCRM or Dolibarr when a team wants a modern stack (React, Postgres) over PHP.
Each shape has a different difficulty profile: a Zoho migration usually has clean object parity but messy custom-field labels, while a Salesforce migration drags Apex, Flows and validation rules that do not move across at all.
What makes migrating to Twenty easier than the category average is its data model. Custom objects use the same treatment as standard ones — there is no Enterprise gate and no extra licence. Self-host gives you direct PostgreSQL access for power-user bulk imports, which is a path most managed CRMs simply do not offer38.
What makes it harder than the average is that Twenty is still an actively evolving project. The People and Companies standard objects ship with a narrower set of pre-built fields than HubSpot or Salesforce, which means every new workspace spends 30 to 60 minutes creating basic fields before the first import41.
The CSV import path was capped at 2,000 rows in early 2025 and was raised to 10,000 in later releases — the limit is moving, but it is still much tighter than the row caps you may be used to on HubSpot or Salesforce68.
Views, workflows and permissions do not import — they are rebuilt manually after the data lands12. Teams that scope for that rebuild work up front finish on time; teams that assume parity with Salesforce or HubSpot do not.
Twenty's open data model removes lock-in; what it does not remove is the rebuild work for views, workflows and sequences.
The Twenty CRM data model you need to map into
Standard objects, custom objects via metadata UI, junction relations, and the upsert keys you'll wire on every field — the destination schema decoded.
Twenty's CRM is built around a small set of standard objects plus an unrestricted custom-object layer driven from metadata tables36. Workspaces are the multi-tenant boundary — every object, field and record lives inside a workspace, and one Twenty deployment can host many.
Before you can map a field on the source side, you need to know exactly which destination object the row belongs on, what fields it requires, and which value will serve as its upsert key. The table below summarises the standard objects in a Twenty workspace and the additional ones you typically end up creating.
| Object | What it stores | Required | Tier |
|---|---|---|---|
| People | Individuals — contacts, leads, partners | Name (first/last); email recommended as unique key | Standard, all deployments |
| Companies | Organisations associated with people and opportunities | Name; domain recommended as unique key | Standard, all deployments |
| Opportunities | Deals in a sales pipeline | Name, stage, company or contact association | Standard, all deployments |
| Notes | Free-form notes attached to people, companies, opportunities | Title or body, target record association | Standard, all deployments |
| Tasks | To-dos and action items linked to records | Title, due date optional, assignee | Standard, all deployments |
| Workspace Members | Users in the workspace; referenced as owners/assignees | Email; must exist before import to bind ownership | Standard; provision before data |
| Custom Objects | Anything else — Projects, Subscriptions, Volunteers, Listings | Define in Settings → Data Model before importing records | Unlimited; same treatment as standard |
| Junction Objects | Many-to-many connectors between two objects | Enable Junction Relations in Settings → Updates → Lab | Standard, all deployments42 |
People can use email as the unique identifier — Workspace Members are also addressable by email, which is how you bind ownership during a CSV import3. Companies are most reliably matched on domain in the format https://acme.com (Twenty stores the full URL form and rejects acme.com or www.acme.com as not matching)3.
Opportunities, custom objects and any other object without a natural key should use Twenty's internal id (UUID) as the upsert key. You can either let Twenty assign IDs and store them back in the source, or generate UUIDs in the source and pass them in. Re-importing a CSV with previously defined IDs is supported but has known edge cases when columns are omitted33. Plan the unique-key strategy on day one.
Once you import, Twenty validates each row against the field schema before committing — errors highlight in yellow in the UI and you can fix them inline before the import is confirmed22. Custom field types determine validation and storage; the catalogue below covers what you can model and the limits you need to plan around.
| Field type | Limit | Notes |
|---|---|---|
| Text / Long Text | Postgres text (effectively unbounded) | Long Text used for multi-line; no native rich-text yet33 |
| Number | Integer or decimal | Currency is a separate type carrying a currency code |
| Date / Date & Time | ISO-8601 | Date & Time required for activity timestamps |
| Select (single) | User-defined options | Imports must use internal option names, not display labels322 |
| Multi-Select | User-defined options | Multiple values per cell; round-trip caveat on overwrite14 |
| Email / Phone / Domain / Links | Composite types — primary + additional | Use Email for People; Domain for Companies |
| Relation | Many-to-one or one-to-many | Reference parent by id or unique field (email/domain)3 |
| JSON | Postgres JSONB | Structured data store; not formula-aware |
| Rating / Boolean / Currency | 1–5 / true-false / decimal+code | Boolean must import as TRUE/FALSE uppercase3 |
| Computed / Formula | Not yet supported | Open feature request — rebuild as workflow or app-side logic11 |
Relationships in Twenty are modelled as relation fields on the object. Many-to-many is supported via a junction object pattern — you create an intermediate object (for example, Project Assignment) with two many-to-one relations, then enable the Junction Relations lab toggle to render linked records directly instead of the intermediate row42.
There is no native master-detail cascade-delete: deleting a parent does not automatically delete children. If your source platform relied on cascade semantics, reproduce them in a Twenty workflow on the parent's Deleted event, or rely on the underlying Postgres foreign-key behaviour when self-hosting with a custom schema.
Pre-migration prep — the work before you touch Twenty CRM
What must be true on the source, the destination, and across the team before the first row hits the import wizard.
The single best predictor of a clean Twenty migration is how much work you do on the source side before the first import button is pressed. Twenty's own documentation frames migration as 'an opportunity for a fresh start — don't bring over clutter'12, and the import wizard is unforgiving about fields that do not yet exist on the destination object.
Fields must exist before import. Uploading a CSV creates records but does not create fields.
Twenty Documentation
Treat the source export as raw material that needs to be shaped to Twenty's expected formats — email lowercased, phone normalised to E.164 with country codes, domains rewritten to the https://acme.com form, select values converted to internal option names, dates rewritten to ISO-8601, booleans uppercased to TRUE/FALSE3.
Source-side prep
- Audit and dedup the source database before export. Twenty does not ship pre-built dedup tooling outside of a manual Merge Records action introduced in 1.3.0, so duplicates landing during import become a manual cleanup task.
- Decide what to leave behind — outdated contacts with no activity in 2+ years, unused custom fields, test data, opt-outs. Twenty's docs explicitly recommend pruning before migration12.
- Normalise emails to lowercase and trim whitespace. Email is the natural unique key for People and Workspace Members.
- Rewrite domains to the canonical
https://domain.comform. Twenty stores domains with the URL prefix and will not matchdomain.comorwww.domain.com3. - Convert select-field display labels to internal option names for every dropdown — pipeline stages, status fields, custom enumerations. Enable Advanced Mode in Twenty Settings to see the internal name for each option2226.
- Generate or preserve a stable external ID — either keep the source platform's primary key in a custom field, or pre-allocate UUIDs that will become Twenty's
idon import.
Destination-side prep
- Decide self-host vs. Twenty Cloud before you provision. Self-host runs on Docker Compose with PostgreSQL and Redis, needs at least 2 vCPU and 4 GB RAM, and gives you direct database access. Cloud (
app.twenty.com) bills at $9/user/month and removes the infrastructure burden. - Stand up a test workspace as a sandbox. Twenty's free tier and self-host model make this trivial: spin up a parallel instance, dry-run the import, validate, then re-run against the production workspace.
- Invite users before importing data. Twenty's docs are emphatic — if your import references owners or assignees by email, those users must exist in the workspace first, otherwise relations cannot be mapped83.
- Pre-create every custom object and custom field under Settings → Data Model. The CSV import creates records, never fields — uploading a column for a non-existent field returns an unmapped column error38.
- Configure select-field options with the internal option names you plan to use in your source-side transformation, not the human display labels.
People prep
Cutover only works if humans cooperate. Lock down a source-system freeze window — typically 24 to 72 hours — and communicate it to every department that touches the CRM. Train sales reps on Twenty's table and Kanban views, the Command Menu (the ⋮ icon used to trigger imports), and the workflow rebuild plan.
A typical small-team Twenty migration runs one to two business days end-to-end; a 50,000-record consolidation with custom objects and historical activities runs one to two weeks of elapsed time. Build the human runway accordingly.
Import mechanisms: CSV wizard and direct database access
Two paths in, each with different limits and shapes. Picking the wrong one is how a Twenty migration stalls at scale.
Twenty exposes load paths whose right choice depends on dataset size, object mix, and whether you need to re-run idempotently. The CSV import wizard covers most one-shot migrations under 50,000 records. Direct PostgreSQL access on self-host adds a path for power users prepared to bypass the application layer entirely38.
CSV import wizard
The native import lives in the Command Menu — open the object's table view, click the ⋮ icon top right, then Import records18. Supported formats are CSV (recommended), XLSX and the legacy XLS13. Each file must contain only one object type — People in one file, Companies in another, Opportunities in a third18.
Steps: download the template to confirm column names, upload the CSV, map columns to Twenty fields, review errors highlighted in yellow and fix them inline in the UI, then confirm the import22. Pre-import validation runs before the records are written, so you can correct a malformed boolean or an unrecognised select value without polluting the workspace22.
Limits: 10,000 records per file in current releases, up from the original 2,000-row cap68. Twenty's documentation recommends splitting 10,000–50,000-record loads into multiple files38151.
Direct PostgreSQL (self-host only)
Self-hosted Twenty exposes its underlying Postgres database. For power-user bulk imports — hundreds of thousands of records, custom-object loads with complex relations, or migrations where you want SQL-level transactional control — connecting directly to the database and writing rows is the fastest path38. The trade-off: you bypass Twenty's validation layer, the Metadata schema mapping, and the application-side change events, so workflows will not fire for inserts done this way.
Mapping your data into Twenty CRM
The longest section — because field mapping is where almost every Twenty migration that fails actually breaks.
Mapping is where every migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether Kanban views work on day two, whether workflows fire correctly on day five, and whether your team trusts the data on day thirty.
Work object by object, top to bottom of the import order specified in Twenty's own documentation: Companies first (no dependencies), then People (depend on Companies), then Opportunities (depend on Companies and People), then Notes and Tasks (depend on the records they attach to), then Custom Objects83151.
Companies
| Source | Destination | Note |
|---|---|---|
| account_name / company_name | name | Required |
| website / domain | domainName | Format strictly as https://acme.com — not acme.com or www.acme.com3 |
| industry | industry (or custom Select field) | Map source labels to Twenty internal option names; create the field first |
| annual_revenue | annualRecurringRevenue (Currency) | Strip currency symbols; provide value plus currencyCode (USD/EUR) |
| employees | employees (Number) | Integer; strip commas |
| owner / account_owner | accountOwnerId (relation to Workspace Members) | Map by user email; the user must exist in Twenty first83 |
People
| Source | Destination | Note |
|---|---|---|
| first_name / last_name | name.firstName / name.lastName | Composite Name field; supply both sub-keys |
| emails.primaryEmail | Lowercased; recommended unique key | |
| phone | phones.primaryPhoneNumber + primaryPhoneCountryCode | Normalise to E.164 before import |
| job_title | jobTitle | Single-line text |
| company / organisation | companyId (relation) | Use companyDomain cross-reference (https://acme.com) on the People CSV83 |
| linkedin / twitter URLs | linkedinLink / xLink (Links) | Composite type — primary URL plus optional label |
| owner | createdBy / pointOfContact relation | Use user email; pre-provision users83 |
Opportunities and pipelines
Recreate every pipeline-equivalent stage in Twenty before importing Opportunities. Twenty currently models pipeline as the stage Select field on the Opportunity object — Kanban view groups records by stage153. Multiple pipelines on one object (record types in Salesforce parlance) are an open community request, not native today153, so teams consolidating multiple source pipelines typically either: (a) keep them as separate Select options on a single Opportunity object, or (b) create one custom object per pipeline for full isolation.
| Source | Destination | Note |
|---|---|---|
| opportunity_name / deal_name | name | Required |
| stage / pipeline_stage | stage (Select) | Use internal option name, not display label; create option first22 |
| amount | amount (Currency) | Provide amountMicros + currencyCode (USD, EUR) |
| close_date | closeDate | ISO-8601 date |
| primary_contact | pointOfContactId (relation to People) | Cross-reference by email or id |
| account / company | companyId (relation to Companies) | Cross-reference by domainName (https://acme.com) or id |
| owner | Workspace Member relation | Map by user email; pre-provision |
Custom-field mapping strategy
Resist the urge to map every source custom field one-to-one. Migrate only the custom fields used by an active process, view or report in the last 12 months. Twenty's documentation explicitly endorses this: 'don't bring over clutter — what to leave behind: outdated contacts, duplicate records, test data, unused custom fields'12.
For Select fields whose source values do not match the destination, either: (1) extend the destination Select with the missing internal option names, (2) collapse adjacent values during transform, or (3) introduce a parallel Text field that holds the legacy value verbatim.
Formula and rollup fields do not import and are not yet supported as a Twenty field type11 — rebuild the calculation in a workflow that fires on record-write, or compute it in the source layer and store the result in a static Number field.
Historical activities — notes, tasks, emails, calls
Twenty has Notes and Tasks as first-class standard objects32. Historical free-form notes from a source CRM should be transformed into Notes records, each with a body, a createdAt timestamp, and a relation to the target record (Person, Company or Opportunity). Source activities of type Task become Twenty Tasks with dueAt, assigneeId and the same target-record relation.
Historical emails and calendar events are handled differently. Twenty's email and calendar sync (Google or Microsoft, with SMTP/CalDAV for others) is configured per-workspace-member under Settings → Accounts and runs forward-looking102. There is no bulk historical-email importer in the way HubSpot ships one; if you need to preserve old email threads as activities, the working pattern is to transform each email into a Note record attached to the matching person, with the email body as the Note body.
Rich-text formatting in source notes is currently lossy — Twenty has an open request for a rich-text field type and the existing Long Text type renders as plain text103. Convert HTML email bodies to plain text or Markdown before import.
Files and attachments
Attachments do not import via the CSV path. Twenty supports attachments on People, Companies, Notes and Tasks (the Attachments feature on Opportunity standard object is an open issue121) — files are uploaded through the UI, then linked to the parent record.
For large attachment estates the working pattern is the same as Twenty itself recommends for most file storage: keep originals in S3, Google Drive or your storage provider, write a deep link into a custom Links field on the Twenty record, and only inline-upload the most recent or most-referenced subset. Self-hosted Twenty uses local volume storage by default (STORAGE_LOCAL_PATH=/data/twenty) with S3 configurable as an alternative100.
Audit trail, ownership and original timestamps
Standard createdAt, updatedAt, createdBy and the internal id UUID are Twenty-managed system fields. The CSV path stamps createdAt to import time; if you need to preserve the original audit trail, the pattern is to create two custom Date & Time fields per object — Legacy Created At and Legacy Updated At — and populate them from the source export.
Owner assignment during import works only if the Workspace Member email exists at the moment of import; rows whose owner cannot be resolved import without an owner relation set, which silently breaks downstream owner-based workflows83.
Audit-trail granularity has historically been a community concern — earlier releases lacked a built-in action history visible to admins132. Newer releases ship a per-record activity log, but for compliance-grade audit trails on a self-host deployment, the durable answer is Postgres-level logging or a downstream warehouse stream rather than reliance on the application UI alone.
CRM-specific: lead scoring, sequences, email/calendar sync
Lead scoring as a first-class feature does not exist in Twenty — there is no scoring rule builder analogous to HubSpot Score or Salesforce Einstein Lead Scoring. The working pattern is a custom Number field (leadScore) updated by a Twenty workflow on record events.
Sequences and cadences are not native. Practitioners migrating from Outreach, Salesloft, HubSpot Sequences or Pipedrive Smart Docs need a different model — the workflow builder can chain wait-steps and task creations but lacks the cadence ergonomics of dedicated tools30. For teams that depend on sequences, plan to pair Twenty with an external cadence tool, or wait on the workflow roadmap.
Email and calendar sync for ongoing forward-looking activity is configured per Workspace Member under Settings → Accounts with Google, Microsoft, or SMTP/CalDAV102. Do not enable sync during the import window or you will get a flood of duplicate Notes as the connector backfills against the same people you are loading.
The pitfalls that derail Twenty CRM migrations
Failure modes ranked by impact, each tied to the exact Twenty mechanism that breaks.
Validation and cutover
What to verify after the import job, in what order — and how to fail safely when something is wrong.
Validation is the bridge between the import finishing and users being allowed in. Practitioners recommend a three-stage validation for Twenty: a test load of 10 percent of records with stakeholder spot-checks, the full load with real-time monitoring of record counts and relation integrity, and a 30-day post-migration audit. The most reliable signal is having department reps verify their own records — they know what right looks like better than any reconciliation script.
Build a reconciliation queries spreadsheet that compares source and destination on each of these counts. Anything outside a 0.5 percent variance gets investigated before users get login access.
- Total People imported vs source — minus deliberately excluded rows (role-based emails, opt-outs, stale 2+ year contacts).
- Total Companies imported vs source — checking that domain-based dedup did not under- or over-merge.
- Total Opportunities per pipeline stage vs source, plus sum of
amount— a non-trivial dollar variance usually signals a stage-mapping error or a Currency precision drop (Twenty stores amounts in micros). - Total Notes and Tasks per parent record type imported vs source — and a date-bucketed comparison to confirm the legacy
createdAtround-tripped into the custom Date field. - Relations per object type — count People→Company, Opportunity→Company and Opportunity→Person relations and compare against the source-derived expected counts.
- Owner distribution — group by
accountOwnerand confirm no record landed unowned that should not have. Cross-check that every distinct owner in the source resolved to a Workspace Member. - Unique-identifier integrity — count distinct emails on People and distinct
domainNamevalues on Companies; duplicates indicate the dedup transform missed cases.
On top of reconciliation, run a manual spot-check protocol: pick 30 random records across objects via the table view filter, open each one, and verify every field against the source UI. Pick five high-value Opportunities and trace the full relation graph — point of contact, company, notes, tasks, attachments. If a non-trivial discrepancy shows up in three or more of the 30, halt the load, fix the root cause, and re-import the affected rows by id.
Rollback in Twenty is not a single button. Twenty 1.3.0 added a Merge Records action that lets you collapse duplicates after the fact, but there is no bulk-undo of an entire import.
The working rollback strategy is: export everything before the import starts (via the table view's export action, or SELECT * FROM against the workspace schema on self-host), stamp every imported row with an Import Batch ID custom Text field, and if catastrophe strikes, filter by that batch ID and bulk-delete from the table view, then re-import from the cleaned source.
On self-host, the strongest rollback option is a Postgres pg_dump immediately before cutover — restoring from that snapshot is the closest thing to an atomic undo Twenty offers. Twenty Cloud customers should request a workspace snapshot from Twenty support before the import if rollback is critical.
Cutover sequencing runs in seven steps. (1) Source goes read-only and the team is notified. (2) Final delta export captures everything that changed during the test-import window. (3) Delta is imported in the same Companies → People → Opportunities → Notes/Tasks → Custom Objects order83.
(4) Reconciliation runs. (5) Views, workflows and permissions are rebuilt. (6) Users get login access and a 48-hour hyper-care window with the migration lead on call. (7) Source decommission is scheduled for 30 to 90 days out, never the same day.
Migration partners and tools
Implementation partners, iPaaS vendors, and specialist migration shops — what each is good for and how to choose.
Twenty maintains an Implementation Partners programme listed inside the documentation; partners are referenced by Twenty's own docs as the people to call for very large datasets38. Certified Twenty partners typically run fixed-scope migration packages — Salesforce-to-Twenty, HubSpot-to-Twenty, custom workflow rebuilds — alongside ongoing managed services that cover schema evolution and version upgrades after cutover.
Managed-deployment providers are a separate but adjacent ecosystem: several PaaS vendors ship one-click Twenty deployments starting around $14/month for small teams, and open-source self-host orchestrators offer documented Twenty configurations in their community discussions100. These are infrastructure providers, not migration consultancies — they get the server running but the data move is still on you.
On the ETL and iPaaS side, Fivetran, Airbyte, Workato and Stitch can all be used to stage source data into a warehouse, transform it with SQL, then write into Twenty. As of mid-2026 the prebuilt Twenty connectors on these platforms are thin — most teams write a small Node.js or Python script rather than waiting for a managed connector.
Managed-migration cost ranges vary widely. A clean HubSpot- or Pipedrive-to-Twenty move of under 25,000 contacts with no historical activities and standard objects only often lands in the $500–$3,000 range from specialist migration vendors, with 48-hour turnaround. A Salesforce-to-Twenty project with custom objects, historical activities and workflow rebuild typically runs $5,000–$25,000+, with the upper end driven by record count, custom-object complexity, historical-data depth and the number of integrations that need re-pointed.
Self-service is genuinely viable for small teams: Twenty Cloud at $9/user/month plus a weekend of CSV preparation is enough for a 5,000-record consolidation. The cost case for outsourcing rises sharply with custom-object count, historical-activity depth, and Salesforce-Apex-style logic that needs to be rebuilt as Twenty workflows.
For teams that want to outsource the migration end-to-end, FlitStack specialises in Twenty CRM migrations and handles the field mapping, Select option-name conversion, historical-data preservation, custom-object schema setup, and validation work described in Sections 5 and 7 of this guide. Pricing is fixed-fee, based on record count and source platform, with separate line items for custom objects, historical activity depth, and self-host vs. Twenty Cloud delivery so the scope is transparent before signature.
This is one of several legitimate paths — the right choice for any given team depends on whether they want a certified Twenty partner, a self-service approach, an iPaaS-backed pipeline, or a specialist migration vendor. [Explore FlitStack →](/contact)

