The Freshsales migration guide
Why teams migrate to Freshsales
The four shapes a Freshsales migration takes, and what makes the platform easier — or harder — than the category average.
Freshsales is the sales CRM inside the Freshworks Customer Engagement Suite, the company also known for Freshdesk and Freshservice. The product was originally launched as a standalone CRM and is now sold as Freshsales Suite — the bundled CRM, marketing automation, chat and telephony offering that succeeded the older Freshsales Classic and Freshmarketer Classic SKUs1.
The typical Freshsales customer is a small to mid-market sales team — 10 to 200 reps — that wants pipeline, sequences and Freddy AI scoring without the per-seat cost and admin overhead of Salesforce. Compared with HubSpot Sales Hub, Freshsales positions itself on flat per-user pricing instead of a contact-tier model; compared with Pipedrive, it positions on the integrated Freshworks suite (one tenant for sales, marketing and support) plus Freddy AI deal insights.
The shapes of migration that actually land on Freshsales tend to fall into four patterns. First, HubSpot exits, driven by contact-tier pricing creep at the $2M–$10M revenue band where the bill triples as the list grows without any new feature usage2. Second, Pipedrive consolidations, where a team needs marketing automation, telephony and chat alongside the deal pipeline and would rather have one vendor than four.
Third, Salesforce downsizes — teams that bought Sales Cloud for the brand and never used Apex, Flows or the AppExchange, and want a flat-rate CRM with the same Leads/Accounts/Opportunities mental model. Fourth, Freshsales Classic upgrades — existing customers being moved by Freshworks itself onto Freshsales Suite under the published plan-mapping table1.
Each shape has a different difficulty profile: a Pipedrive migration usually has clean object parity, while a Salesforce migration brings rich automation that does not move across at all.
What makes migrating to Freshsales easier than the category average is the native CRM Migration tool itself — Freshworks ships pre-built importers from Pipedrive, Salesforce, Zoho and HubSpot that accept the source platform's own zip export and map default and custom fields automatically up to 25,000 records for instantaneous import12.
What makes it harder than the average is the per-tier custom-field cap — the Sprout (Free) plan allows zero custom fields per entity, Blossom (Growth) allows 10, and only Forest (Enterprise) opens up to 450 across the core modules3. Teams who do not check this number against their source schema discover mid-import that they need to upgrade the tier before they can even land the data.
Workflows, Sales Sequences, Freddy AI scoring rules and reports do not import — they are rebuilt from documentation. Teams that scope for that work 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.
The Freshsales data model you need to map into
Objects, custom fields, relationships, and the upsert keys you'll wire on every record — the destination schema decoded.
Freshsales is built around a small set of standard modules plus optional Custom Modules on higher tiers. The platform's object model splits people into two records — Leads for unqualified inbound and Contacts for qualified prospects associated with an Account. Leads were temporarily removed in the older Freshsales Classic generation and reintroduced in the current Suite as a separate module; do not assume your source platform's single People object collapses neatly into one Freshsales module.
Before you can map a field on the source side, you need to know exactly which destination module the row belongs on, what fields it requires, and which value will serve as its unique identifier for upsert. The table below summarises the modules you will touch in a Freshsales Suite migration.
| Object | What it stores | Required | Tier |
|---|---|---|---|
| Contacts | Qualified people associated with an Account | Last name (email recommended as unique key) | All plans |
| Leads | Unqualified inbound prospects before account association | Last name, email | All plans (reintroduced in Freshsales Suite) |
| Accounts (Sales Accounts) | Companies / organisations | Name | All plans |
| Deals | Revenue opportunities in a pipeline stage | Deal name, sales pipeline, deal stage, deal value | All plans |
| Notes | Free-text notes attached to any record | Body, target record | All plans (20 MB attachment cap per note) |
| Tasks | Open or completed to-do items with owners and due dates | Title, owner, due date | All plans |
| Appointments | Calendar meetings logged against records | Title, start time, attendees | All plans |
| Documents / Files | Trackable attachments | File, owning record | 150 MB per file; storage scales with seat count |
| Products | Catalogue of sellable items linked to deals | Name, price | Pro and above |
| Custom Modules | Customer-defined record types | Schema defined first; per-field requirements | Enterprise (Forest) — up to 310 custom fields per module |
Contacts and Leads use email as the de-facto unique identifier — Freddy AI's duplicate detection on the Pro plan matches new records against existing rows on email. Accounts use name plus an optional custom cf_domain_name property as the practical upsert key, since the Sales Accounts bulk upsert path requires you to declare which property carries the unique value4.
Deals and Custom Module records have no natural unique key, so create a single-line text custom field, mark it unique, and use it as your external ID during bulk upsert.
Custom field availability is the most important number in this section. Freshsales caps custom fields per entity by plan tier — Sprout offers zero, Blossom 10, Garden 150, Estate 305 and Forest 450, with Custom Modules getting their own 310-field ceiling on Forest3.
| Field type | Limit | Notes |
|---|---|---|
| Text field (single-line) | 255 chars | Stores any alphanumeric string |
| Paragraph / multi-line text | ~65,000 chars | Line breaks preserved on import |
| Number | Integer or decimal | Strip currency symbols and thousands separators |
| Date | YYYY-MM-DD | Timezone-stripped — date values can shift by one day on import5 |
| Datetime | ISO-8601 | Stored in account timezone |
| Dropdown (single-select) | ~250 options | Picklist values are case-sensitive on import |
| Multi-select / checkbox | ~250 options | Semicolon-delimited on CSV/XLSX import6 |
| Lookup / relationship | Enterprise only for cross-module lookups | Required field on Custom Modules to bind parent records |
| Formula field | Enterprise / Forest only | Does not import — rebuild on-platform |
| Custom fields per entity | 0 / 10 / 150 / 305 / 450 (Sprout → Blossom → Garden → Estate → Forest) | Custom Modules get a separate 310-field cap on Forest3 |
Relationships in Freshsales are modelled as lookups between modules: Contacts associate to one or more Accounts, Deals associate to a primary Contact and an Account, and Custom Modules associate via lookup fields to standard modules7. There is no master-detail-style cascade-delete: deleting a parent does not delete children, which is behaviour you may need to reproduce in a workflow if your source platform relied on it.
Custom Modules (Forest / Enterprise) participate in lookups the same way standard modules do. They are loaded via the same bulk upsert path and accept their own custom fields, with the 310-cap noted above3.
Pre-migration prep — the work before you touch Freshsales
What must be true on the source, the destination, and across the team before the first row hits the import tool.
The single best predictor of a clean Freshsales migration is how much work you do on the source side before the first import button is pressed. Freshworks Support's own best-practice article warns that fixing errors after the load is more expensive than fixing them in the CSV, and recommends a final clean run after a deliberate test load9.
Configure Freshsales fully — users, custom fields, territories, pipelines — before the import, not after. Source-side fixes are an order of magnitude cheaper than destination-side cleanup.
Treat the source export as raw material that needs to be shaped to Freshsales's expected formats — email lowercased, phone normalised, picklist values made case-exact, multi-select values joined with semicolons, dates rewritten to YYYY-MM-DD, and owners resolved to Freshsales user email addresses that already exist in the destination.
Source-side prep
- Audit and dedup the source database before export. Freddy AI duplicate detection on the Freshsales side is Pro-and-above and runs after records land — case-variant emails will become two contacts unless you normalise upstream.
- Normalise emails to lowercase, trim whitespace, and strip role-based addresses (info@, sales@) that you do not want to flood the Contacts module with.
- Match picklist values case-exactly — Freshsales drop-down imports treat the value as case-sensitive, and a row whose
Stage = Newwill fail to map to a picklist value namednew11. - Convert multi-select values to semicolon-delimited strings in the CSV/XLSX — Freshsales splits on
;for multi-select fields and will treat a comma-separated value as a single literal string6. - Stamp a stable external ID on every record in the source export — a UUID or the source platform's primary key — and store it in a custom unique field so re-runs and reconciliation are deterministic.
- Decide what is in scope for historical activities. Notes, Tasks and Appointments can be imported, but past Email conversations require the Freshsales email-sync historical import which runs after mailbox connection13.
Destination-side prep
- Create a Sandbox under Admin Settings → Other SFA Settings → Sandbox if you are on the Forest / Enterprise plan — Sandbox is gated to that tier, only org admins can create one, and you can have one sandbox at a time8. On lower tiers, use a free trial account as a throwaway dry-run instance.
- Provision users first under Admin Settings → Users with the exact email address you will reference in the
Sales Ownercolumn, otherwise unmatched owners default to the importing admin and silently break owner-based workflows14. - Pre-create every custom field on the right module with the right type — Sprout supports zero custom fields, and even on paid tiers a Number field cannot be retroactively changed to Decimal after data lands3.
- Build sales pipelines and deal stages before importing any deals — Freshsales rejects deal rows whose stage does not exist on the named pipeline.
- Configure territories and round-robin assignment rules so they run on imported data correctly9. Workflow Automation rules should be paused during the import to avoid triggering notifications on backfilled records.
- Define Custom Modules and their lookup fields before importing. Custom Module schemas must exist before records of that type can be loaded.
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 Freshsales Kanban deal boards, the Contacts/Leads split and the Freddy AI insights panel before go-live, not after.
A small Pipedrive-to-Freshsales migration under 25,000 records runs as an instantaneous import12; anything larger is queued by Freshworks and processed in off-peak hours over one to two business days. Build the human runway accordingly.
Import mechanisms: UI wizard and CRM Migration tool
Two main paths in, each with different limits and shapes. Picking the wrong one is how mid-migrations stall at scale.
Freshsales exposes two main load paths and the right one depends on dataset size and source platform. The native UI Import covers most one-shot migrations under 25,000 records. The CRM Migration tool ships pre-built importers from Pipedrive, Salesforce, Zoho and HubSpot. Third-party ETL tools sit on top of both and add staging, transformation and dedup layers.
UI Import (CSV / XLSX)
The native import lives on each module's list-view page — click Contacts → Import Contacts, Deals → Import Deals, or the equivalent on Accounts and Leads6. The import accepts CSV and XLSX files up to 5 MB per file11 and requires a column that maps to Last Name for Contact and Lead imports.
It offers two modes: Create new records only, or Create new + update existing — the upsert path that matches on a chosen unique field6.
Multi-select fields require values separated by semicolons (;) in the CSV — comma separation is treated as a single string6. Mandatory custom fields block the import if the column is missing or empty11; bad rows are reported in an error-log email sent to the importing admin after the job finishes. The right call: UI for one-shot loads under 25,000 records on standard modules, or any time you want a visual mapping review before commit.
CRM Migration tool (pre-built source importers)
Freshsales ships a CRM Migration experience that accepts the source platform's own zip export and runs a static field mapping. The Salesforce variant accepts the standard Salesforce data export zip and imports Leads, Contacts, Accounts, Opportunities, Events and Tasks CSV files directly15. The Pipedrive variant runs the same pattern with a zip export and maps default plus custom fields by exact name12.
Custom-field auto-mapping requires the destination custom field to exist with the exact same display name as in the source export, so the prep step in Section 3 — creating Freshsales custom fields with matching names — is non-optional. The CRM Migration tool handles up to 25,000 records as an instantaneous load; over that, Freshworks queues a migration request and processes in 1–2 business days during off-peak hours12.
Third-party staging tools
Tools like Airbyte, Fivetran, Stitch and Hevo all expose a Freshsales source/destination connector. Their role in a one-time migration is rarely the move itself — they are the staging layer that lands source data in a warehouse, the transformation layer that converts picklist case and resolves owner emails, and the ongoing-sync layer that takes over once the cutover is done.
Mapping your data into Freshsales
The longest section — because field mapping is where almost every migration that fails actually breaks.
Mapping is where every migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether reports work on day two, whether Workflow Automations fire correctly on day five, and whether your sales team trusts the data on day thirty.
Work module by module, top to bottom of the import order: Accounts first (so Contacts and Deals can lookup to them), then Contacts and Leads, then Deals, then Notes / Tasks / Appointments, then Custom Modules and Products.
Contacts and Leads
Freshsales splits people into Leads (unqualified inbound) and Contacts (qualified, account-bound). Decide your boundary before import: a common rule is that source records with a non-empty Account and any logged activity become Contacts, while everything else lands as a Lead. Importing the same person twice (once as Lead, once as Contact) is the most common preventable failure on day one.
| Source | Destination | Note |
|---|---|---|
| email (de-facto unique key) | Lowercase before import; matched by Freddy AI dedup on Pro+ | |
| first_name / last_name | first_name / last_name | Last Name is mandatory — rows without it fail11 |
| phone | mobile_number / work_number | Two distinct fields; normalise format before import |
| owner / account_owner | Sales Owner | Map by user email; user must exist in Freshsales first14 |
| lifecycle / status | Lifecycle stage / Lead stage | Picklist values case-sensitive11 |
| tags | Tags | Semicolon-delimited string in CSV6 |
| source / lead_source | Lead source | Pre-create missing dropdown options before import |
| territory | Territory | Configure territory assignment rules before load so they run on the import9 |
Accounts (Sales Accounts)
| Source | Destination | Note |
|---|---|---|
| company_name | name (required) | Freshsales Accounts module — name is the human upsert key |
| website / domain | cf_domain_name (custom field) | Create as unique custom field; use as unique_identifier_name in bulk_upsert4 |
| industry | industry | Single-select; pre-create missing options |
| annual_revenue | annual_revenue | Number — strip currency symbols |
| parent account | Parent Account lookup | Set in a second pass once both parents and children are loaded |
Deals and pipelines
Recreate every sales pipeline and every deal stage in Freshsales before importing deals. Each stage has a numeric probability that drives forecasting; build the mapping table source-stage → Freshsales-pipeline + Freshsales-stage-name. Deals whose stage value does not match any stage on the named pipeline are rejected by the importer with no automatic remap.
If you are consolidating multiple source pipelines, the cleanest approach is to keep them as separate Freshsales pipelines for at least 90 days post-migration, then merge once reporting has stabilised. The Deal value field is mandatory in Freshsales — if your source records carry null or blank amounts, populate them with 0 before import, as the Freshsales Support team explicitly recommends, or the rows will fail9.
| Source | Destination | Note |
|---|---|---|
| deal_name / opportunity_name | deal_name | Required |
| stage / pipeline_stage | deal_stage | Case-sensitive; must exist on the named pipeline |
| amount | deal_value | Mandatory — backfill blanks with 09 |
| close_date | expected_close | YYYY-MM-DD; watch the off-by-one timezone bug5 |
| owner | Sales Owner | Map by user email; deal owner drives forecasting |
| primary_contact | Related Contacts (semicolon-delimited emails) | For multiple contacts per deal, separate emails with ;19 |
| account / organisation | Sales Account lookup | Use account name or cf_domain_name in a second pass |
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 or report in the last 12 months. Freshsales caps custom fields per entity at 10 (Blossom), 150 (Garden), 305 (Estate) or 450 (Forest)3 — and the CRM Migration tool's auto-mapping requires the destination custom field to exist with the exact same name as the source column, so every extra field is also extra prep work.
For picklist fields whose source values do not match the destination, either: (1) extend the destination dropdown with the missing options pre-import, (2) collapse adjacent values during transform, or (3) introduce a parallel custom field that holds the legacy value verbatim. Formula fields are Enterprise / Forest only and do not import — they are recomputed on-platform, so any source formula must be rebuilt as a Freshsales formula field on Forest or replicated via Workflow Automation on lower tiers.
Historical activities — notes, tasks, appointments, email and call history
Notes, Tasks and Appointments can be loaded via CSV import, each row carrying its own created_at and target record. For historical email conversations, Freshsales ships a Past Email Sync option under Profile icon → Connect Email → Edit Sync Settings, which pulls Gmail or Outlook threads and matches them to existing Contact and Lead records13.
Historical email sync can be configured per user profile only once13, so users must exist and have mailboxes connected before the sync window is set. Past call logs from third-party telephony providers rarely round-trip — the fallback is to attach a flat call-summary note per record with the original timestamp in the body text.
Files and attachments
Attachments do not import in bulk via the CSV path. The supported path is the Files feature — note attachments cap at 20 MB per file20, standalone documents in the Files module accept up to 150 MB per file21, and total storage scales with seat count at roughly 2 GB per user on paid plans22.
For large attachment estates, the pattern most teams adopt is: keep originals in S3 or Google Drive, store a deep-link URL in a custom field on the parent record, and only upload the most recent subset inline. There is no native batch file-import path, so attachments are attached per record in the UI after parents land.
Audit trail, ownership and original timestamps
Standard created_at and updated_at are system-managed — they are stamped on import day and cannot be overwritten during a CSV load. To preserve the original audit trail, create two custom fields per module — Legacy Created Date and Legacy Created By — and populate them from the source export.
Owner assignment during import works only if the Sales Owner column contains the email of a user who already exists in Freshsales14. Rows whose owner cannot be resolved fall to the importing admin, which silently breaks owner-scoped views, territory rules and Workflow Automations that filter by owner.
CRM-specific: lead scoring, Sales Sequences, Freddy AI, email/calendar sync
Freshsales Lead Score is computed by Freddy AI on the Pro plan and above, based on contact properties, deal stage transitions and engagement signals. Scoring models do not import — they accrue forward once the data lands. If you must preserve historical scores, put them in a Legacy Lead Score custom number field.
Sales Sequences (multi-step email cadences) do not have an import mechanism — recreate them manually under Sales Sequences → Create New and re-enroll active prospects post-cutover. Workflow Automations, IntelliAssign rules and Smartforms are rebuilt the same way.
Email and Calendar Sync (Gmail / Outlook) is connected per user under Profile icon → Connect Email after users are provisioned13. Do not enable two-way sync during the import window or you will get a flood of duplicate engagements as the connector backfills the same Contacts you are loading.
The pitfalls that derail Freshsales migrations
Nine specific failure modes — ranked by impact, each tied to the exact Freshsales 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. Freshworks Support's own best-practice flow recommends a deliberate three-stage validation: a sample test load, full review of the error-log email, and a final run after errors are resolved9. 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 Contacts and Leads imported vs source — minus deliberately excluded rows (role-based emails, bounced lists, opt-outs).
- Total Accounts imported vs source — checking that name-based collapse did not over-merge two legitimately separate companies.
- Total Deals per pipeline per stage vs source, plus sum of deal_value per pipeline — a non-trivial dollar variance usually signals a stage-mapping error or a currency-precision drop.
- Total Notes / Tasks / Appointments per type imported vs source — and a date-bucketed comparison to confirm activity dates round-tripped.
- Lookup integrity — count Contacts with a populated Account, Deals with a Primary Contact, and Deals with an Account; compare against the source-derived expected counts.
- Owner distribution — group by Sales Owner and confirm no record landed under the default importing admin that should have been assigned to a specific rep14.
- Unique-identifier integrity — count distinct emails on Contacts and Leads; any duplicates indicate the dedup transform missed a case-variant or the same person was loaded into both modules.
On top of reconciliation, run a manual spot-check protocol: pick 30 random records across modules and verify each field against the source UI. Pick five high-value deals and trace the full lookup graph — primary Contact, Account, Products, Notes, Appointments. 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 external ID.
Freshsales does not ship a bulk-undo for imports. The Recycle Bin holds deleted records and supports restoration, but the documentation explicitly notes that you can only bulk-delete records from one page at a time23 — there is no one-click rollback for a multi-thousand-row import. The Recycle Bin retains deleted records for a limited window before purge, after which only a Freshworks Support ticket can recover them.
The practical rollback strategy is therefore: export everything to S3 before the import starts, stamp every imported row with an Import Batch ID custom field, and if catastrophe strikes, filter by that batch ID and bulk-delete page by page, then re-import from the cleaned source. The Freshworks Best Practices article explicitly recommends this cycle — fix errors, delete records, rerun full migration9.
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 through the UI or CRM Migration tool with the same unique-identifier column; (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.
Migration partners and tools
Freshworks Partners, iPaaS vendors, specialist migration shops — what each is good for and how to choose.
The Freshworks Partner Directory lists Authorized, Authorized Platinum, Distributor and Service Partner tiers across more than 50 countries24. For Freshsales migrations specifically, partners with explicit Salesforce-to-Freshsales, HubSpot-to-Freshsales or Pipedrive-to-Freshsales practices tend to ship cleaner than generalist Freshdesk-leaning implementation shops, because the data-model nuances of the Contacts/Leads split and Sales Sequence rebuild are not the same skill set as ticket-system migration.
A5 Solutions, Abano and the broader Authorized Platinum tier appear in the directory as named regional resellers and implementation partners24. Freshworks itself also operates an internal Data Migration team that handles the CRM Migration tool's queued large-volume runs (over 25,000 records, 1–2 business days off-peak) at no additional cost as part of the subscription12.
On the ETL and iPaaS side, Airbyte, Fivetran, Stitch and Matillion all have Freshsales connectors. Their role in a migration is rarely the migration itself — they are the staging layer that lands source data into a warehouse, the transformation layer that converts picklist case and resolves Sales Owner emails to existing Freshsales users, and the ongoing-sync layer that takes over once the one-time migration is complete.
Hevo Data publishes a dedicated Freshsales pipeline that rebuilds the source schema in the warehouse for downstream consumption.
Managed-migration cost ranges vary widely. A clean Pipedrive-to-Freshsales move of under 25,000 contacts with no historical activities and standard modules only often lands in the $500–$3,000 range with a setup fee plus per-object pricing. A Salesforce-to-Freshsales project with deal history, Custom Modules, historical activities and Marketo decoupling typically runs $5,000–$30,000, with the upper end driven by record count, custom-field complexity, historical-data depth and the number of integrations that need rebuilding rather than re-pointed.
For teams that want to outsource the migration end-to-end, FlitStack specialises in Freshsales migrations and handles the field mapping, Contacts/Leads boundary decisions, picklist case normalisation, historical-data preservation 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 Modules and historical activity depth 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 regional Authorized Partner, the in-house Freshworks Data Migration service, an iPaaS-first warehouse approach, or a specialist migration vendor. [Explore FlitStack →](/contact)




