The Definitive Guide to Migrating to Nutshell

Nutshell is a sales-focused CRM built by Nutshell Inc. for small and mid-sized B2B teams that want a working pipeline, email sequences and reporting without a Salesforce-style admin function ¹. The product is a Sales Suite with five plan tiers — Foundation, Growth, Pro, Business and Enterprise — plus add-ons like Power AI and the Nutshell IQ prospecting bundle ²⁸.

The typical Nutshell customer is a 5 to 100-seat sales organisation — agencies, manufacturers, professional services and SMB SaaS — that wants pipeline visibility wired to email sync without paying Salesforce-tier economics. Compared with HubSpot Sales Hub, Nutshell positions on flatter pricing; compared with Pipedrive, on richer email marketing and AI summarisation; compared with Zoho CRM, on cleaner UX.

The shapes of migration that actually land on Nutshell tend to fall into four patterns. First, spreadsheet exits — teams that have outgrown Google Sheets pipelines and want a CRM with contact merge, email logging and pipeline reporting. Second, Salesforce or HubSpot downgrades, driven by total cost of ownership on teams that never used Apex, Flows or marketing automation heavily.

Third, legacy replacements — Act!, Insightly, Capsule, Highrise, SugarCRM or homegrown databases — where the source schema is loose and the project is really a re-architecture. Fourth, M&A consolidation, where an acquired business runs on a different CRM and the parent standardises on Nutshell. A Pipedrive migration has clean object parity; a Salesforce migration carries rich automation that does not move across at all.

What makes migrating *to* Nutshell easier than the category average is the import tool itself — it accepts CSV files, runs through a mapping wizard with field-level previews, and ships an Import2-powered direct-from-CRM path for sources including Salesforce, HubSpot, Pipedrive and Zoho ²²⁷⁸. Custom fields are addressable on every paid plan.

What makes it harder than the average is the four-object record model — People, Companies, Leads and Accounts — which forces a split that Pipedrive and HubSpot users do not have to think about. Custom-field counts are also plan-tier gated, which catches mid-market teams off guard when they discover the cap in the middle of mapping.

Pipelines, stages, email sequences, lead scoring rules and reports do not import — they are rebuilt from documentation. Teams that scope for the rebuild up front finish on time; teams that assume parity do not.

Teams that scope for the rebuild work up front finish on time; teams that assume parity do not.

Nutshell's CRM is built around four core record types — People, Companies, Leads and Accounts — surrounded by activities, notes, tasks and pipelines. The split between Leads (open opportunities) and Accounts (closed-won customers) is the most important shape to internalise before any field mapping starts.

Before you can map a field, you need to know which destination object the row belongs on, what fields it requires, and which value serves as its match key. The table below summarises the objects you will touch in a Nutshell migration.

People are matched by exact name first, then email address on import — if neither matches, a new contact is created ¹⁵⁰. Companies use company name as the match key. Leads have no natural unique key, so either let Nutshell assign Lead IDs and store them back, or carry the source platform's deal ID in a custom Text field on the lead.

Once a record is created, its Nutshell ID is the canonical primary key for any update path — re-importing the same CSV without a stable external ID column creates duplicates that have to be merged manually after the fact ⁷⁸. Plan for this on day one.

When you import via the CSV wizard, Nutshell creates new records by default and offers a deduplication step for matches. Custom-field types determine validation; the catalogue below covers what you can model and the per-plan limits to plan around.

Relationships are modelled as associations between People, Companies and Leads — a Lead can carry multiple People (decision maker, influencer, end user) and one primary Company. Accounts associate to Companies and the People who work there. There is no formal junction object; the platform leans on tags, custom fields and the Lead-Person link table to express many-to-many.

Pipelines are first-class — every Lead lives in exactly one pipeline with one stage. Multiple pipelines per account are supported on paid plans, and each pipeline carries its own Stage list, Confidence percentages and automation. Stages do not cascade, so the same logical stage name may need to be created on every pipeline you build ¹⁵⁶.

The single best predictor of a clean Nutshell migration is how much work you do on the source side before the first import button is pressed. Nutshell's own best-practice guide is explicit that file setup decides whether records land correctly — encoding, column separation and field formatting are the fix, not post-import cleanup ⁴¹.

The single best predictor of a clean migration is how much work you do before the first import button is pressed.

Treat the source export as raw material that needs shaping to Nutshell's expected formats — saved as UTF-8 CSV, each piece in its own column, phone numbers normalised, dates rewritten to a consistent format, Decision values matched to the picklist created in Nutshell, owners resolved to existing user accounts ⁴¹.

Source-side prep

• Audit and dedup the source database before export — Nutshell merges People on exact name first and email second, so duplicates that share neither land as separate records and have to be merged in the UI one at a time ¹⁵⁰.
• Normalise emails to lowercase, trim whitespace, and strip role-based addresses (info@, sales@). Casing differences are not always caught by the matcher.
• Stamp a stable external ID on every record — a UUID or the source platform's primary key — and map it into a custom Text field per object so re-runs are deterministic.
• Decide what is in scope for historical activities. Calls, meetings, tasks and logged emails can be imported with an activity date stamp, but Products can only be imported alongside Leads ¹¹³.
• Save the file as UTF-8 — Nutshell's importer rejects other encodings with an error page immediately after upload, before any mapping happens ⁷⁹.

Destination-side prep

• Trial a sandbox account by starting Nutshell's 14-day free trial in a separate workspace and dry-running the import end-to-end before you load production. Nutshell ships no formal sandbox on lower tiers, so the trial workspace is the practical stand-in.
• Provision users first and confirm their email addresses match the source export's Owner column exactly — Nutshell maps owners by email, and rows whose owner email is missing land unowned.
• Pre-create every custom field on the right object with the right type — Text vs Long Text vs Decision matters, and changing a field's type after creation usually means recreating it.
• Build every pipeline and stage before importing Leads — Leads targeting a non-existent stage are rejected or land in the pipeline's default stage rather than where you intended ¹⁵⁶.
• Decide your default lead owner and assignment rules before kicking off the import — automatic lead distribution can fight with importer behaviour if both are active.

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 Activity logging, Lead Confidence updates and pipeline drag-and-drop before go-live, not after. A small-business migration runs one to two business days; a complex multi-pipeline Nutshell migration runs two to four weeks of elapsed time. Build the human runway accordingly.

Nutshell exposes two main load paths and the right one depends on dataset size and source platform. The native CSV Import wizard covers one-shot migrations under a few tens of thousands of records. The Import2-powered direct-CRM tool handles common SaaS sources end-to-end.

Native CSV Import wizard

The CSV importer lives under Setup → Import (or Settings → Data → Import on newer accounts) and walks through file upload, object selection, column mapping, and a preview step before commit ²²¹⁴¹. Three object types are supported: Companies, People and Leads. The wizard tracks past imports under an Import History list at the bottom of the same page ⁷⁵.

File requirements: CSV format with UTF-8 encoding, each field in its own column, header row drives mapping ⁴¹⁷⁹. Public documentation does not specify a hard row cap, but practitioners chunk files at 5,000–10,000 rows per upload to keep mapping responsive. Products can only be imported attached to Leads — there is no standalone product importer ¹¹³.

Import2 direct-CRM migration

For migrations from other CRMs, Nutshell partners with Import2 to offer one-click migration from sources including Salesforce, HubSpot, Pipedrive, Zoho CRM, Insightly, Highrise, Capsule CRM, Copper, SugarCRM and Act!¹⁴¹. The flow starts a free sample of up to 100 random Accounts plus their People, Leads and activities so you can verify mapping before committing.

Salesforce migrations have a dedicated path: Nutshell directly accepts the .zip file from Salesforce's Setup → Data Export tool ⁷⁸. Some Salesforce plans cap exports at once per month, so plan the export window against the cutover date.

Mapping is where every migration earns its scars. The schema decisions in your mapping spreadsheet determine whether reports work on day two, whether pipeline drag-and-drop fires the right automation on day five, and whether your sales team trusts the data on day thirty.

Work in import order: Companies first (so People and Leads can associate), then People, then Leads, then Activities and Notes, then Accounts and Products if you are on a plan that includes them.

People

Companies

Leads and pipelines

Recreate every pipeline and stage in Nutshell before importing Leads. Each stage carries a Confidence percentage that drives forecast math — *Initial Contact* might be 10%, *Qualified* 40%, *Proposal* 70%, *Closed Won* 100%. Build the mapping table source-stage → Nutshell-pipeline + stage-name. Leads targeting a non-existent stage are rejected or land in the pipeline's default stage ¹⁵⁶.

If you are consolidating multiple source pipelines, keep them as separate Nutshell pipelines for at least 90 days post-migration, then merge once reporting has stabilised. Each pipeline carries its own stages — they do not cascade — so the same name ("Qualified") may need to be created on every pipeline.

Custom-field mapping strategy

Resist the urge to map every source custom field one-to-one. Migrate only fields used by an active process or report in the last 12 months. Excess fields weaken governance, eat into the plan-tier custom-field budget, and make Power AI's timeline summarisation less effective.

For Decision (picklist) fields whose source values do not match the destination, either: (1) extend the Nutshell Decision field with the missing options before import, (2) collapse adjacent values during transform, or (3) hold the legacy value verbatim in a parallel custom Text field. Source calculation properties do not import — Nutshell has no formula custom field, so precompute formula values during transform and drop them into a static Number, Currency or Text field.

Historical activities — emails, calls, meetings, notes, tasks

Nutshell supports importing activities with their original timestamps via the activity date field — this determines where each engagement lands on the People/Company/Lead timeline. Activity types map to Calls, Meetings, Logged Emails and Tasks; custom Activity Types can be created in Settings before import to mirror the source ⁷⁴.

Emails logged through Nutshell's email sync (Gmail/Outlook) appear on the timeline once a user connects their mailbox — but that path is post-cutover. For pre-cutover historical emails, export them from the source as a CSV of subject/body/timestamp/contact-email rows and load them as Logged Email activities through the importer. Rich HTML is accepted but plain-text often renders cleaner.

Power AI on the Pro plan adds timeline summarisation that distils long activity histories into AI overviews on demand. The feature reads whatever activities exist in Nutshell — so importing historical activities compounds in value on a Power AI plan. Zoom transcripts can also be summarised post-import via the Zoom integration.

Files and attachments

Attachments do not flow through the CSV importer. The supported path is to attach files manually in the UI after import. Public documentation does not publish a per-file size cap; practitioners report that very large files sometimes fail through the UI uploader and are best stored in S3 or Google Drive with a deep link in a custom URL field.

For large attachment estates (hundreds of GB), the pattern most teams adopt is: keep originals in external object storage, store a deep link in a custom URL field on the Nutshell record, and only inline-upload the most-referenced subset.

Audit trail, ownership and original timestamps

Nutshell-managed system fields — record created date, modified date, internal IDs — cannot be overwritten during CSV import. To preserve the original audit trail, create two custom fields per object — *Legacy Created Date* (Date) and *Legacy Created By* (Text) — and populate them from the source export.

Owner assignment during import works only if the owner email matches a provisioned Nutsheller at the moment of import; rows whose owner cannot be resolved fall back to the importing user as owner, which silently breaks downstream territory-based reports until corrected.

Account-wide change auditing is available via the Audit Log feature, but only on the Enterprise plan ¹³⁰. Lower plans can see Import History under Setup → Import to confirm which imports landed, but not per-field change history. Plan for this if compliance reporting is a hard requirement.

CRM-specific: lead scoring, email sequences, email/calendar sync

Lead-scoring models do not import — Nutshell uses Confidence percentages tied to pipeline stages plus optional per-lead overrides. To preserve historical lead scores, put them in a *Legacy Lead Score* custom Number field and let Confidence accrue forward from import day.

Email sequences (Nutshell's drip cadence tool) do not have an import mechanism — recreate the structure manually in Settings → Sequences and re-enroll active prospects post-cutover. Sequences are tied to People records, so People must land before sequences are turned on.

Email and calendar sync (Gmail/Outlook) is set up per user under Settings → Sync email *after* users are provisioned ¹⁴⁹¹⁵⁸. Do not enable it during the import window or you will get a flood of duplicate timeline entries as the connector backfills. Nutshell's block list under Settings → Email security keeps HR, payroll and legal threads out of the synced timeline ¹⁵⁸.

Validation is the bridge between the import finishing and users being allowed in. The most reliable signal is having department reps verify their own records — they know what right looks like better than any script. Run a three-stage protocol: a 10 percent test load with stakeholder spot-checks, the full load with real-time record-count monitoring, and a 30-day post-migration data-quality audit.

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, bounced lists, unsubscribed).
• Total Companies imported vs source — checking that name-based merge did not over-collapse orgs with similar names.
• Total Leads per pipeline per stage vs source, plus sum of Value per pipeline — a non-trivial dollar variance signals a stage-mapping error or currency-precision drop.
• Total activities per type (Calls, Meetings, Logged Emails, Tasks) vs source — plus a date-bucketed comparison to confirm activity date round-tripped ⁷⁴.
• Lead → Person and Lead → Company associations — count primary contacts and primary companies on Leads against source-derived expected counts.
• Owner distribution — group by Lead owner and confirm no record landed unowned or assigned to the importing admin by mistake.
• Match-key integrity — count distinct People by name and Companies by name; unexpected merges indicate the matcher caught name overlaps you didn't expect ¹⁵⁰.

On top of reconciliation, run a manual spot-check protocol: pick 30 random records across People, Companies and Leads and verify each field against the source UI. Pick five high-value Leads and trace the full association graph — primary Person, Company, products, recent Activities. If discrepancies show in three or more of the 30, halt the load, fix the root cause, and re-import the affected rows.

Nutshell ships no native bulk-undo for imports. The closest fallback is Import History under Setup → Import, which lists every import job, type, runner and timestamp ⁷⁵. From there you can identify the records added by a specific import and bulk-delete via the People/Companies/Leads list pages.

The real rollback strategy remains: export everything to S3 before the import starts, stamp every imported row with an *Import Batch ID* custom Text field, and if catastrophe strikes, filter by that batch ID, bulk-delete in the UI, and re-import from the cleaned source.

Cutover sequencing: (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; (4) reconciliation runs; (5) users get login access and a 48-hour hyper-care window with the migration lead on call; (6) source decommission is scheduled for 30 to 90 days out, never the same day.

Nutshell's migration ecosystem centres on a small number of dedicated CRM-migration vendors plus the usual ETL/iPaaS connector landscape. The Import2 partnership is the closest thing to an official path — surfaced inside the Nutshell UI under Settings → Data → Import → Another CRM and supporting Salesforce, HubSpot, Pipedrive, Zoho, Insightly, Copper and Capsule¹⁴¹.

Other specialist vendors include Import2 (the embedded option), ClonePartner (engineer-led custom migrations with fixed-price quotes) and category platforms with Nutshell connectors. Each offers fixed-scope packages, sample migrations of around 100 records to validate mapping before commit, and post-migration support windows.

On the ETL and iPaaS side, Fivetran, Airbyte, Stitch, Workato and Zapier all have some level of Nutshell connector coverage ¹²¹. Their role is rarely the migration itself — it is the staging layer that lands source data into a warehouse, the transformation layer that converts Decision-field values, and the ongoing-sync layer after cutover.

Airbyte and Fivetran are common picks for warehouse-first teams; Workato is common where the migration is bundled with workflow automation rebuilds; Zapier handles the long tail of low-volume SaaS-to-Nutshell connections.

Managed-migration cost ranges vary widely. A clean Pipedrive-to-Nutshell move of under 25,000 records with no historical activities often lands in the $500–$3,000 range; ClonePartner publishes that 95% of their migrations cost less than $3,000. A Salesforce-to-Nutshell project with custom fields, historical activities and multiple pipelines typically runs $3,000–$15,000, with the upper end driven by record count, custom-field complexity and historical-activity depth.

For teams that want to outsource the migration end-to-end, FlitStack specialises in Nutshell migrations and handles the field mapping, historical-data preservation, Decision-field option-list conversion, 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 historical activity depth and the number of pipelines 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 the embedded Import2 flow, an iPaaS-first approach, or a specialist migration vendor. Explore FlitStack →