Nutshell is account-centric, GHL is contact-centric. CSV exports flatten relationships. Use API migration or a managed service for anything beyond a flat contact list.
There is no native migration path between Nutshell and GoHighLevel. Nutshell uses a B2B account-centric data model where Companies contain People and Leads link to both, while GoHighLevel is contact-centric with Opportunities tied to single Contacts inside Pipelines. This fundamental architectural mismatch means that CSV exports flatten relational data and orphan activity histories, requiring custom API-level work to rebuild Nutshell's multi-entity relationships within GoHighLevel's flatter schema. Serious migrations demand explicit architectural decisions around multi-contact deals, company hierarchies, and product data before any data is moved.
Read this first
Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.
Important update
GoHighLevel's Custom Objects are now available on every subscription tier (Starter, Unlimited, Pro) — up to 10 Custom Objects per sub-account. Earlier guides may reference Custom Objects as a Pro-only feature. That constraint no longer applies. (help.gohighlevel.com)
Nutshell API edge case
Nutshell's API does not return a WWW-Authenticate header on 401 responses, which violates RFC 2617. Some HTTP clients (especially .NET) won't automatically retry with credentials. Force the Authorization header on the first request.
Upsert safety
GHL's POST /contacts/upsert is only as safe as your duplicate settings. If one existing contact matches email and another matches phone, GHL updates whichever field has higher priority in that location's duplicate configuration and ignores the other. Freeze your duplicate settings before running dry runs. (marketplace.gohighlevel.com)
Critical mapping decisions
1. Nutshell Leads with multiple People — GHL Opportunities link to a single Contact. Choose a primary contact per Opportunity, or create duplicate Opportunities (one per person). 2. Lead Products — GHL Opportunities have a single monetary value, not an itemized product list. Either sum the product values or create a Custom Object for line items. 3. Activities — Nutshell tracks calls, meetings, and emails on a shared timeline. GHL doesn't replicate this structure. Import as Notes with a standardized prefix to preserve context.
Business Name automation gotcha
If you use GHL's Business Name automation to create companies from imported contacts, exact text matters. Misspellings or spacing differences will create wrong company associations and force cleanup. (help.gohighlevel.com)
Rollback execution note
GHL's bulk-delete in the UI works for tagged records, but there is no public API endpoint for bulk contact deletion. If you need programmatic rollback, you must iterate over records and delete them individually via DELETE /contacts/{contactId}. For large migrations, this means your rollback path is significantly slower than your load path — another reason to validate thoroughly before production cutover.
The runbook
Work top to bottom. Tick steps as you go — your progress is saved in this browser.
01 Discovery Agree scope, pipeline design and success criteria before touching data.
Objective A scope covering every object in the revenue model, with sales leadership signed up to the pipeline design.
Keep these open
-
Inventory every object in Nutshell
Count accounts, contacts, leads, deals or opportunities, activities, notes, emails, files, products and quotes. Activity and email history is usually the largest object by an order of magnitude and the one people forget to size.
Data Profiler Get real record counts instead of estimating from memory -
Map the current pipeline and agree the target model
Document every pipeline, stage, probability and required field, then agree the HighLevel model with sales leadership. Migrating a broken pipeline faithfully is a wasted opportunity; redesigning it mid-migration is a wasted migration.
Stage changes alter historical conversion rates. Agree how you will restate reporting before you change the model.
-
Catalogue integrations and automation
List every system touching Nutshell: marketing automation, quoting, billing, ERP, data enrichment, dialler, BI. Each is a separate cutover task with its own owner, and each can silently write bad data into your new CRM.
-
Capture the reporting that must survive
Interview the people who actually live in the dashboards — forecast, pipeline coverage, rep activity, cohort conversion. Every one of these needs the underlying fields to migrate, which frequently expands the scope.
-
Build the business case and pick the go-live date
Model licence delta, implementation effort and productivity dip. Then choose the date deliberately: mid-quarter is disruptive, quarter-end is worse. Most teams land on the first week of a new quarter.
COI & ROI Calculator Build the 36-month business case you will need for sign-off
Nutshell → HighLevel specifics
- Cost consolidation and marketing automation
- Nutshell is a strong sales CRM, but marketing features are limited. GoHighLevel bundles CRM, pipeline management, marketing automation, funnels, SMS/email, and appointment scheduling into a single subscription starting at $97/month. Teams running Nutshell plus a separate email platform, landing page builder, and scheduling tool often find GHL cheaper in aggregate. (nutshell.com)
- Agency model fit
- GoHighLevel was built for agencies. Its sub-account architecture, white-labeling, and SaaS Mode let agencies resell the platform under their own brand. Nutshell doesn't offer this.
- Workflow consolidation
- Nutshell excels at pipeline management for B2B teams but lacks the built-in funnel builders, SMS marketing, and appointment booking that GHL includes natively.
Don't move on until
- Object counts confirmed for accounts, contacts, deals and activities
- Target pipeline and stage model agreed with sales leadership
- Reporting requirements captured from the people who use the reports
02 Data Audit CRM data is usually dirtier than anyone expects. Find out how dirty.
Objective A profiled export with duplicates, ownership gaps and relationship integrity all quantified and triaged.
Keep these open
-
Export and profile every object
Profile null rates, distinct values and type consistency across all objects. Pay attention to fields sales reps were supposed to fill in: an 80% null rate on a field your forecast depends on is a business finding, not a data one.
Data Profiler Profile the Nutshell export for nulls, outliers and type drift -
Quantify duplicates and agree the merge policy
Measure duplicate accounts (same company, different spellings and suffixes) and contacts (same email, or same person at a renamed company). Agree survivorship rules before merging: which record wins, which fields, and what happens to the activity history on the loser.
Merging before you have agreed survivorship rules destroys history irreversibly. Decide first, merge second.
Data Cleaner Strip empty rows, stray whitespace and dead columns -
Verify relationship integrity
Check every deal has a valid account, every contact a valid account, every activity a valid parent. Referential breaks are the defect that turns a clean-looking load into a CRM where the pipeline report does not tie to the account list.
-
Resolve ownership and the user map
Build the Nutshell user → HighLevel user map, including leavers. Every record needs a valid owner: records assigned to deactivated users either fail to load or land unassigned, and unassigned pipeline is pipeline nobody works.
Records owned by deactivated users are a top cause of load failures. Decide the reassignment target before you start.
-
Scan for PII and regional compliance
CRMs hold marketing consent, lawful basis and unsubscribe state. Confirm these fields migrate intact and that consent provenance survives — losing consent records is a regulatory problem, not a data-quality one.
PII & Compliance Scanner Find regulated fields before they land in a new system -
Clean, normalise and archive the pre-state
Normalise country and state values, phone formats, currencies and casing, and standardise all timestamps to UTC. Keep an untouched copy of the raw export — it is your only reference if a mapping decision turns out wrong.
-
Export a GHL backup
before migration starts (if the account has existing data)
Don't move on until
- Duplicate rate quantified per object with a merge policy agreed
- Every record has a valid owner mapped to a target user
- Relationship integrity verified — no orphaned deals or contacts
03 Field Mapping Map objects, relationships and picklists — in that order.
Objective A signed mapping spec that covers objects, relationships, picklist values and currency handling.
Keep these open
-
Map objects and their relationships first
Establish how Nutshell objects correspond to HighLevel objects before any field work. Leads-versus-contacts, accounts-versus-organisations and deal hierarchies differ structurally between CRMs, and a field map built on the wrong object model has to be redone.
Schema Mapper Opens pre-loaded with the Nutshell → HighLevel field pair -
Generate and then hand-review the field map
Auto-match both schemas, then review every row. Look hardest at anything named "type", "source", "stage" or "status", where names match and meanings do not.
-
Map every picklist value, including retired ones
Enumerate all values on both sides — deal stages, lead sources, industries, statuses — and map each explicitly, including values no longer offered but still present on old records. Unmapped values either fail the row or land as blanks that quietly break segmentation.
Historical records often carry picklist values that were retired years ago and no longer appear in the UI.
-
Decide currency, amount and date handling
If you sell in multiple currencies, confirm how HighLevel stores amounts, exchange rates and dated conversion rates. Recalculating historical deal values at today's rate silently rewrites your revenue history.
Multi-currency deals re-converted at current rates will not tie to your historical reporting or your finance system.
-
Determine the load order
Sequence the load so parents exist before children: users, then accounts, then contacts, then deals, then activities and notes. Keep source IDs in custom fields so relationships can be rebuilt by lookup rather than guesswork.
-
Freeze the spec and sign off
Version-control the mapping, walk RevOps and sales leadership through the decisions that change reporting, and get written sign-off before the pilot.
-
Normalize phone numbers
to E.164 format (GHL rejects non-standard formats)
Data Format Converter Reshape the export into the format HighLevel's importer expects -
Split full names
into first/last if Nutshell stores them as a single field
-
Map picklist values
create a lookup table for Nutshell Industries → GHL custom field options
Nutshell → HighLevel specifics
- Truncate notes
- to 5,000 characters for CSV import (API has no limit)
Don't move on until
- Object and relationship model mapped and reviewed
- Every picklist value explicitly mapped, including dead values
- Load order determined so parents always exist before children
04 Test Migration Pilot with related records, not a flat sample.
Objective A pilot load whose relationships, ownership and roll-up reporting all verify against source.
Keep these open
-
Configure the HighLevel sandbox to match the agreed model
Build the pipelines, stages, custom fields, record types and user roles first. Load into a default configuration and you will only discover the configuration defects at full scale.
-
Select a connected pilot slice
Take complete account trees — 50-100 accounts with all their contacts, deals, activities and files — rather than a flat random sample. Relationship defects are the whole point of a CRM pilot and a flat sample cannot expose them.
-
Run the load in dependency order with full logging
Load users, accounts, contacts, deals, then activities, logging every request against its source ID. Note which failures are transient (rate limits, timeouts) and which are structural (validation, missing parent).
-
Verify relationships and roll-ups
Confirm every deal sits on the right account with the right owner and stage, and that pipeline totals per account and per rep match Nutshell exactly. Roll-up mismatches almost always mean a relationship or currency defect upstream.
Migration Validation Tool Diff the pilot batch against source before scaling up -
Measure throughput and project the full load
Record actual records-per-hour under HighLevel's API limits and extrapolate, remembering activity history usually dominates volume. If the projection exceeds your window, split the load or trim activity scope now.
-
Let reps work the pilot data
Put two or three reps in the sandbox against their own accounts. They spot missing context, wrong owners and unusable notes far faster than any reconciliation script, and their buy-in is what makes adoption work.
Don't move on until
- Relationships intact across the whole pilot slice
- Pipeline roll-ups match source for the pilot accounts
- Reps have worked pilot records and confirmed they are usable
05 Cutover Switch the revenue system with the pipeline intact.
Objective All in-scope CRM data live in HighLevel, integrations repointed, and reps selling on day one.
Keep these open
-
Pre-load history ahead of the freeze
Load closed deals, historical activities and inactive accounts while Nutshell stays live. Only open pipeline and the final delta need to move inside the window.
-
Publish the cutover runbook
A timed sequence with owners and abort criteria: freeze, final export, delta load, integration switch, smoke test, go/no-go, rep enablement. Pick a window that avoids quarter-end and month-end close.
-
Freeze Nutshell and take the final delta
Set Nutshell read-only and export everything changed since the pre-load. Reps updating deals during an unenforced freeze is the classic way to lose the most recent — and most valuable — pipeline changes.
A rep who updates a deal in the old CRM during the freeze will lose that update permanently.
-
Load the delta and reconcile the pipeline
Run the delta, then verify open pipeline value and count per rep against Nutshell before anything else. If the pipeline number is wrong on day one, reps stop trusting the system and never fully come back.
Migration Validation Tool Confirm the final delta landed before you reopen -
Repoint every integration and verify with real records
Switch marketing automation, quoting, billing, enrichment, dialler and BI connections, then push a live record through each path. An unrepointed integration writing into the old CRM causes divergence that gets harder to reconcile every day.
Two-way integrations left pointing at the old CRM will keep writing there. Disable them before you switch, not after.
Cron Expression Builder Schedule the delta syncs that run through the freeze -
Go/no-go, then enable the reps
Call the decision explicitly against the exit criteria. Run enablement on real data with their own accounts on screen, and keep Nutshell read-only rather than cancelled until validation closes.
-
Keep Nutshell active
until GHL is fully validated — run both systems in parallel for 1–2 weeks
Nutshell → HighLevel specifics
- Tag all imported records
- with a migration batch tag (e.g., migration-batch-1) so you can bulk-delete if needed
- Maintain the source-to-target ID crosswalk
- so you can delete and reload selectively rather than starting from scratch
Don't move on until
- Historical load complete and reconciled before the freeze
- All integrations repointed and verified end to end
- Reps logged in with pipeline visible and correct
06 Validation Prove the revenue numbers tie out, then close the project.
Objective Reconciled data, forecast parity with pre-migration reporting, and signed acceptance.
Keep these open
-
Reconcile every object
Compare counts and values across accounts, contacts, deals, activities and files, plus field-level spot checks on a random sample. Produce a single report suitable for audit and for finance.
Migration Validation Tool Reconcile Nutshell and HighLevel record-for-record -
Tie the pipeline and forecast to baseline
Rebuild forecast, pipeline coverage and win-rate reporting and compare to pre-migration figures. Every variance needs an explanation — most trace back to stage or currency mapping decisions made in Field Mapping.
Stage-model changes will legitimately shift historical conversion rates. Restate the baseline rather than chasing the difference as a defect.
-
Verify ownership, visibility and permissions
Confirm every record has the right owner and that sharing rules, territories and role hierarchy give each rep exactly the visibility intended. Over-broad visibility in a CRM is a data-protection issue as much as a config one.
-
Re-profile for field completeness
Compare loaded null rates against the source profile per field. A field that arrived empty while counts matched is the failure counts alone cannot detect.
Data Profiler Prove field completeness held up through the load -
Test automation and integration write-back
Fire every workflow, assignment rule, sequence and notification, and confirm each integration writes correctly in both directions. Automation is rebuilt rather than migrated, so it is unproven until observed.
-
Sign off and schedule decommission
Get written acceptance against the Discovery criteria, keep Nutshell read-only for 30-90 days with a final archive export taken, then diarise cancellation so the contract does not auto-renew.
Don't move on until
- Full reconciliation report complete across all objects
- Forecast and pipeline reports tie to pre-migration baselines
- Acceptance signed and Nutshell decommission scheduled
Field mapping reference
The field-by-field mapping for each object. Use this as the starting point for your mapping spec.
Object GoHighLevel Target
| Nutshell field | HighLevel field | Notes |
|---|---|---|
| Company | Company | GHL Companies are a grouping tool — less feature-rich than Nutshell's Company object. One contact can link to one Company. |
| Person | Contact | 1:1 mapping, but Contact is the top-level entity in GHL. |
| Lead | Opportunity (in Pipeline) | Map Nutshell pipeline stages → GHL pipeline stages. One Lead = one Opportunity. |
| Lead Products | Opportunity monetary value OR Custom Object | GHL Opportunities carry a value but not itemized products. Sum values or create a Custom Object for line items. |
| Lead Source | Contact Source field OR custom field | Depends on your attribution model. |
| Activity (Call/Meeting) | Note on Contact | GHL doesn't have a native Activity log matching Nutshell's timeline. Import as Notes with a prefix (e.g., [CALL - 2025-03-15]). |
| Task | Task on Contact | Direct mapping available. |
| Tag | Tag on Contact | 1:1 mapping. |
| Custom Field | Custom Field (matching type) | Create custom fields in GHL before import. |
| Parent-Child Company | Company + Custom Object association | Requires Custom Objects for child entities. |
Risk matrix
Per-object risk for this pair. Plan extra validation around anything marked high.
| Object | Risk | Notes |
|---|---|---|
| Contacts (People) | low | Nutshell People map directly to GoHighLevel Contacts as flat records, making this the most straightforward entity to migrate via CSV or API. |
| Companies | medium | Companies transfer as a concept but lose parent-child hierarchies and multi-contact associations, since GoHighLevel only allows one Company per Contact and has no native org hierarchy. |
| Leads / Opportunities | high | Nutshell Leads are relational records spanning multiple Companies and People, but GoHighLevel Opportunities must be linked to a single Contact inside a specific Pipeline stage, requiring significant restructuring. |
| Activity History | high | Timeline events distributed across Nutshell Companies, People, and Leads must be consolidated onto GoHighLevel Contact notes with a 5,000-character cap, risking data truncation and loss of entity-level context. |
| Custom Fields | medium | Custom fields on Nutshell Companies, People, and Leads must be remapped to GoHighLevel's custom field schema, with potential type mismatches and the need to pre-create fields before import. |
| Product Data | high | Nutshell's structured product and pricing data on Leads has no native equivalent in GoHighLevel Opportunities and must be modeled via Custom Objects limited to 10 unique fields per object. |
| Email History | high | Nutshell's full data export only includes truncated email content, making complete email thread migration effectively impossible without Enterprise-tier SQL access. |
| Tasks | low | Tasks export from Nutshell as a separate CSV and can be recreated on GoHighLevel Contacts, though assignee mapping and due date formatting require manual alignment. |
| Notes | medium | GoHighLevel's CSV importer only supports one note per contact record with a 5,000-character maximum, so contacts with extensive Nutshell note histories will lose data without API-based migration. |
| Automations and Workflows | high | Nutshell automation logic and sales process configurations have no export mechanism and must be manually rebuilt in GoHighLevel's workflow builder from scratch. |
The hard parts
What makes this specific migration difficult, beyond the mechanics.
Relational Data Model Mismatch
Nutshell's Leads are relationships linking Companies, People, and deals simultaneously, while GoHighLevel's Opportunities attach to a single Contact inside a Pipeline, requiring explicit decisions on how to decompose multi-entity relationships.
Multi-Company Contact Associations
Nutshell allows a Person to belong to multiple Companies, but GoHighLevel restricts a Contact to one Company at a time, forcing data architects to choose a primary association or model secondary relationships via Custom Objects.
Activity and Note History Preservation
Nutshell stores timeline activity across Companies, People, and Leads as separate entities, but GoHighLevel only supports notes and tasks on Contacts with a 5,000-character limit per note, risking truncation and loss of contextual history.
Company Hierarchy Translation
Nutshell's native parent-child Company relationships (available on Pro+) have no direct equivalent in GoHighLevel and must be modeled using Custom Objects with manually created associations.
API Rate Limit Constraints
GoHighLevel enforces a rate limit of 100 requests per 10 seconds, which throttles high-volume migrations and requires batching, queuing, and retry logic to avoid partial record creation.
Product Data Mapping Gap
Nutshell Leads carry structured product data with pricing that has no native equivalent on GoHighLevel Opportunities, requiring either Custom Objects (limited to 10 unique fields) or flattening into custom fields.
Tools used in this playbook
All free, all run entirely in your browser — nothing is uploaded.
FAQ
Can I migrate from Nutshell to GoHighLevel using CSV export?
Yes, but CSV flattens all relational data — Company → Person → Lead links are lost. GHL's CSV importer also limits notes to one per contact (5,000 chars max) and caps file size at 30 MB. CSV works for small, flat contact lists under ~2,000 records. For anything with multi-level relationships or activity history, use the API or a managed service.
What are GoHighLevel's API rate limits for migration?
GHL's V2 API enforces a burst limit of 100 requests per 10 seconds and a daily limit of 200,000 requests, both per Marketplace app per resource (Location or Company). Implement exponential backoff with jitter to handle 429 responses. For a typical migration of 20,000 contacts with opportunities and notes, expect 75,000–150,000 total API calls.
How do Nutshell Leads map to GoHighLevel?
Nutshell Leads (which serve as both leads and opportunities) map to GoHighLevel Opportunities inside Pipelines. The key difference: Nutshell Leads can link to multiple People and Companies, while GHL Opportunities link to a single Contact. You must choose a primary contact per Opportunity and create matching Pipelines and Stages in GHL before importing.
Does GoHighLevel support Custom Objects on all plans?
Yes. Current GHL support docs confirm Custom Objects are available on every plan (Starter, Unlimited, Pro) — up to 10 Custom Objects per sub-account. Earlier references to Custom Objects being Pro-only are outdated. Each object supports up to 10 unique fields and relationships to Contacts, Companies, Opportunities, and other Custom Objects.
How long does a Nutshell to GoHighLevel migration take?
A small CSV-based migration (under 2,000 flat contacts) takes a few hours. A custom API script for 5,000–50,000 records with relationship preservation typically requires 40–80+ hours of engineering time over 2–4 weeks. A managed migration service like ClonePartner typically completes in days, including validation and testing.