Migrate from Twenty CRM to Nutshell

Twenty Company records map directly to Nutshell Organization. We use the Twenty company domain field as the Organization website for deduplication. Organization is imported first because both People (Contact) and Opportunities (Deal) in Nutshell can link to an Organization. No foreign key constraint exists in Nutshell, so we import Organizations before People and use Organization.name as the lookup target for subsequent record batches.

Twenty People records map to Nutshell Person. The key structural difference is that Twenty enforces a required companyId linking each Person to exactly one Company, while Nutshell supports a flexible Person-Organization relationship where a Person can be unlinked, linked to one Organization, or linked to multiple Organizations. For records that had a companyId in Twenty, we create the Person-Organization link in Nutshell after Organizations are created. For unlinked People, we import directly without an Organization association. Email serves as the deduplication key.

Twenty Opportunity maps to Nutshell Deal. Stage names from Twenty (Appointment Scheduled, Proposal Sent, Negotiation, Closed Won, Closed Lost) map to Nutshell pipeline stages that we configure before import. Amount, close date, and probability transfer directly. We resolve the companyId and any personId foreign keys to their Nutshell equivalents (Organization.id, Person.id) at migration time. Nutshell allows Deals without a linked Party (Person) or Organization, so orphaned Opportunities import successfully.

Twenty Tasks map to Nutshell Tasks. We preserve the title, due date, assignee (resolved via owner email to Nutshell User), completion status, and the relational target (linked to Person, Organization, or Deal). Nutshell's Task model does not require a linked Party or Organization, so Tasks attached to any Twenty record type import without blocking on a missing parent.

Twenty Notes map to Nutshell Notes. We map the note body content, author (resolved via owner email to Nutshell User), and the relational target. Nutshell Notes attach to the Person record by default when the source Twenty Note was linked to a Person; we resolve the Person lookup via email at migration time.

Nutshell does not support user-defined custom objects as first-class database entities. Custom Objects from Twenty require a configuration decision during scoping: (a) flat custom fields on Person, Organization, or Deal if the structure is simple (single-level attributes), or (b) a normalized Tasks-based approach if the custom object represents a many-to-one relationship with an event or activity history. We document the schema of each Twenty Custom Object and recommend the target approach before migration. Standard field types from Twenty (text, number, date, select, multi-select) map to equivalent Nutshell field types.

Twenty Owner records map to Nutshell Users. We resolve each Owner by email match against the Nutshell User table. Any Twenty Owner without a matching Nutshell User is held in a reconciliation queue for the customer's admin to provision before record import resumes. Owner assignment on Opportunities and Tasks migrates after the User lookup is resolved.

Twenty engagement records (call, email, meeting, task type) are not separate objects with their own CRUD operations in the same way as standard objects. However, if engagement history is stored as linked activity records, we migrate these as Nutshell Activity logs attached to the relevant Person or Deal. Call disposition, duration, and meeting location transfer to custom Activity fields where Nutshell supports them.