Migrate from EspoCRM to Nutshell

EspoCRM Account records map directly to Nutshell Company records. The company name becomes the primary match key during import. Nutshell Company stores address, website, phone, and industry fields. If EspoCRM stores industry as a multi-enum field with more than 20 options, we split into a single-select Industry field plus a secondary custom field for overflow values.

EspoCRM Contact records map to Nutshell Person records with first name, last name, email, phone, and address fields preserved. Multiple email addresses on a single EspoCRM Contact (multi-email field) are stored as the primary email on the Nutshell Person with secondary addresses in a custom notes field because Nutshell Person does not support a native multi-email structure.

EspoCRM Lead records map to Nutshell Person records. EspoCRM stores lead status, source, and conversion date fields; we preserve these in Nutshell Person custom fields because Nutshell does not have a separate Lead object distinct from Person. The original EspoCRM lead status value is retained for reconciliation audit.

EspoCRM Opportunity records map to Nutshell Deal records. The deal name, amount, stage, probability, expected close date, and description transfer directly. EspoCRM Opportunity stages map to Nutshell Deal stages; we create the Nutshell stages during setup to match the EspoCRM stage names and order before migration begins. Closed-won and closed-lost outcomes map directly.

Each EspoCRM pipeline becomes a set of Nutshell Deal stages. Stage order, names, and probability percentages transfer to Nutshell Deal stages. If EspoCRM uses multiple pipelines, we create separate Nutshell Deal categories or stage sets and assign deals accordingly during import. Nutshell's stage configuration happens in the CRM settings before any deal records are imported.

EspoCRM Case records map directly to Nutshell Case records. Status, priority, resolution, and description fields transfer. The linked Account and Contact references resolve to Nutshell Company and Person IDs during the migration so that case relationships are preserved on import.

EspoCRM Activities (Calls, Meetings, Tasks) map to Nutshell Activity records. Activity type, subject, date, duration, outcome, and description transfer. Each Activity is linked to a Nutshell Person or Company ID resolved from the EspoCRM parent reference. The EspoCRM activity stream order is preserved by setting the Activity date to the original timestamp.

EspoCRM Email activity records migrate to Nutshell Activity records with the email subtype flag. Email body content transfers as the Activity description. Attachments on EspoCRM email records migrate as file references; self-hosted attachment files require the separate filesystem extraction step detailed in the gotchas section.

EspoCRM Campaign records migrate to Nutshell Campaign records with campaign name, status, type, start date, and budget preserved. Nutshell Campaign tracks campaign metadata and links to target People; we create the campaign records and link the targeting list during migration. Email send history does not transfer because it is event-log data rather than record data.

EspoCRM User records map to Nutshell User accounts by email address match. Role assignments and team memberships are preserved in a written inventory for the customer's admin to reconfigure in Nutshell's user management settings post-migration because Nutshell does not expose role hierarchies via its public API in the same way EspoCRM does.

Custom entity types created in EspoCRM via Entity Manager require a schema review before migration. Entities that represent a classification or tag (status, type, category) map to Nutshell custom fields on the nearest standard object (Person, Company, Deal). Entities that represent standalone records with their own relationships are flagged as requiring a manual rebuild in Nutshell because Nutshell does not support arbitrary custom object creation. We provide a custom field creation guide and a 'cannot migrate' summary for each standalone custom entity type.

On self-hosted EspoCRM instances, uploaded files live in the data/files/ directory on the server filesystem, not in the database. We extract the referenced files during the filesystem archive phase, transfer them alongside the database migration, and attach them to the corresponding Nutshell Person, Company, Deal, or Case record. Nutshell supports file attachments on records. Cloud-hosted EspoCRM instances use database-stored attachments that we extract via the API alongside record migration.