The Freshdesk migration guide
Why teams migrate to Freshdesk
The four shapes a Freshdesk migration takes, and what makes the platform easier — or harder — than the category average.
Freshdesk is the customer-support product from Freshworks, founded in Chennai, India in 2010 by Girish Mathrubootham and Shan Krishnasamy1. The company is now headquartered in San Mateo, California and went public on Nasdaq in 2021. Freshdesk sits inside a broader Freshworks suite that includes Freshservice (ITSM), Freshchat (messaging), Freshcaller (voice) and Freshsales (CRM).
The typical Freshdesk customer is a B2C or SMB support organisation — 3 to 500 agents — running inbound volume across email, web portal, social and chat without the admin overhead of Zendesk or ServiceNow. Compared with Zendesk, Freshdesk positions on simpler pricing and a flatter learning curve; compared with Help Scout or Front, it positions on a deeper automation engine and built-in Freddy AI for triage and reply suggestions.
Migration shapes that land on Freshdesk fall into four patterns. First, consolidation: replacing a stack of Zendesk plus Intercom plus a separate KB tool with Freshdesk's combined helpdesk and Solutions KB4. Second, Zendesk exits — driven by pricing pressure or AI-deflection economics where Freddy Copilot replaces Zendesk AI's per-resolution fees.
Third, legacy replacements — shared Gmail inboxes, osTicket, Spiceworks or homegrown ticket systems — where the source has no real schema and the project is really a re-architecture. Fourth, M&A integration, where an acquired business standardises onto the parent's Freshdesk. A Zendesk migration usually has clean ticket-and-user parity but messy trigger logic; a shared-mailbox migration has no schema at all.
What makes migrating to Freshdesk easier than the category average is the Sandbox feature, which builds a full replica of production configuration and lets admins dry-run schema changes and imports before pushing to live27. The native Contacts and Companies CSV importer is forgiving on date formats and auto-resolves duplicates by email.
What makes it harder than the average is that Dispatch'r, Observer and Supervisor rules, Scenario Automations, SLA policies, canned responses and Solutions categories do not import — all rebuild in the admin UI. Throughput is shaped by the plan tier you sit on, and Custom Objects are Enterprise-only, capped at 20 per account11.
Teams that scope the rebuild up front finish on time; teams that assume parity do not.
Freshdesk is flexible and forgiving on the surface, but under the hood it has very clear opinions about how tickets, contacts, agents, groups, and fields fit together.
The Freshdesk data model you need to map into
Tickets, Contacts, Companies, Agents, Groups, Solutions and Custom Objects — the destination schema decoded.
Freshdesk is built around a small set of standard objects with default and custom fields, plus lookup relationships. Solutions (Freshdesk's knowledge base) sits alongside the ticketing schema; Custom Objects extend it on Enterprise.
Before you can map a field on the source side, you need to know exactly which destination object the row belongs on, what fields it requires, and which value will serve as its upsert key. The table below summarises the objects you will touch in a Freshdesk migration.
| Object | What it stores | Required | Tier |
|---|---|---|---|
| Tickets | Support requests across email, portal, phone, chat and social | Requester (email or contact ID), subject, description, status, priority, source | All tiers |
| Contacts | End-users / requesters — individuals who raise tickets | Email (primary unique key) or phone | All tiers |
| Companies | Customer organisations that contacts belong to | Name (unique within account) | All tiers; multi-company per contact requires the feature toggle |
| Agents | Internal users who resolve tickets | Email, name, role; occasional vs full-time flag | All tiers; seat-counted |
| Groups | Agent collections used by routing and SLAs | Name; member agent IDs | All tiers |
| Solutions (KB) | Categories → Folders → Articles, with translations | Category, folder, article title, body | All tiers; multilingual on Growth+ |
| Products | Lines of business in multi-product accounts | Name; primary email | Estate / Forest legacy; succeeded by Workspaces |
| Workspaces | Newer isolation model replacing multi-product | Workspace name; assigned agents and fields | Enterprise (newer accounts) |
| Custom Objects | Customer-defined record types associated to tickets, contacts or companies | Schema defined first; per-field requirements | Enterprise; max 20 per account, 100 fields each11 |
Contacts use email as the default unique identifier — the importer overwrites an existing contact if the CSV email matches one already in the helpdesk9. A contact can hold a primary email plus up to nine secondary emails, allowing one person to span ten addresses9. Companies match on name by default and are case-insensitive on dedup.
Tickets do not have a natural unique key — Freshdesk assigns a sequential ticket ID at creation. The standard pattern is to import with a unique_external_id custom text field on contacts and a custom number or text field on tickets that stores the source platform's ticket number, then use that for reconciliation and any later delta sync.
When you import via CSV, Freshdesk upserts contacts and companies on their unique key: matches update, misses create. Tickets always create — there is no native upsert for ticket CSV. Custom field types determine validation; the catalogue below covers what you can model and the limits to plan around.
| Field type | Limit | Notes |
|---|---|---|
| Text | 255 chars (single-line); larger for paragraph | Stores any alphanumeric string; case-preserved |
| Paragraph (multi-line) | ~64,000 chars | Rich-text not supported; HTML stripped |
| Number | Integer; signed | Numeric filters and reports supported |
| Decimal | Two decimal places by default | Locale-dependent display; store as period-separated |
| Date | YYYY-MM-DD only | Date-only; timezone-stripped — wrong format aborts import16 |
| Dropdown | Up to 3 levels of nesting on dependent fields | Dropdown values are case-sensitive — exact match required12 |
| Checkbox | true / false | Multi-select uses a separate field type |
| Lookup relationship | Up to 5 associations per Custom Object | Custom-Native links Custom Objects to Tickets, Contacts, Companies only13 |
| Custom fields per ticket / contact / company | Plan-gated: Free 0, Growth/Pro/Enterprise scale per type | Custom fields cannot be deleted once data exists; archive instead |
Relationships in Freshdesk are modelled as lookup fields added to ticket, contact or company forms. Native objects support Custom-Native and Native-Custom associations for Tickets, Contacts and Companies only — other native objects do not participate in custom-object associations13. Custom Objects support up to 5 associations each, and a Custom Object record limit is not enforced as a hard ceiling but plan-scaled throughput effectively gates it11.
There is no native master-detail cascade-delete: deleting a parent contact does not delete its tickets — reproduce that in Workflow Automator if your source platform relied on it. Companies-to-contacts is one-to-many by default; a feature toggle enables one contact across multiple companies.
Pre-migration prep — the work before you touch Freshdesk
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 Freshdesk migration is how much work you do on the source side before the first import button is pressed. Practitioners describe it plainly: teams that respect Freshdesk's schema end up with calm migrations; teams that do not spend weeks cleaning up after go-live.
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 to be shaped to Freshdesk's expected formats — email lowercased, phone normalised to E.164 with country code (Freshdesk's phone channel requires +14088481234 style, not 408-848-12349), dropdown values cased exactly as configured in the destination, dates rewritten to YYYY-MM-DD, agents resolved to Freshdesk agent emails.
Source-side prep
- Audit and dedup the source contact list before export — email deduplication should be done on the source spreadsheet, not relied on at import time. Practitioners report 10–25% fuzzy-match false positives in B2B lists where two people share name + company, so dedup requires human review.
- Decide ticket scope — how much history is operationally useful? Two to five years of tickets is common; full history is technically possible but adds little value beyond about three years and substantially increases migration time and storage.
- Normalise emails to lowercase, trim whitespace, and remove role-based addresses (info@, sales@) that you do not want flooding the contact database. Freshdesk will overwrite an existing contact when an import row matches its email9.
- Convert dropdown values to exact destination casing — Freshdesk dropdowns are case-sensitive on import.
Highandhighare different values; mismatches are silently dropped or fail the row12. - Stamp a stable external ID on every record in the source export — the source platform's primary key or a UUID — so re-runs, delta migrations and reconciliation are deterministic.
Destination-side prep
- Build a Sandbox from Admin → Support Operations → Sandbox — a Sandbox is a full replica of your Freshdesk configuration used to dry-run schema changes and imports end-to-end before pushing to production17.
- Provision every agent including inactive or legacy ones needed for historical ticket ownership — rows whose assigned agent does not exist at import time land unowned, which silently breaks group reporting.
- Create groups and assign agents before importing tickets, because group-based routing and SLA policies key off group membership at the moment a ticket is created or imported.
- Pre-create every custom field on the right object (ticket, contact, company) with the right type — text vs paragraph vs dropdown matters because Freshdesk will not let you change a field's type after data has been written to it12.
- Define Custom Objects and their associations before importing related ticket data — Custom Object schemas must exist before records of that type can be created, and a ticket only supports one custom-object lookup per ticket1113.
- Disable automations during import — Dispatch'r, Observer, Supervisor rules, Scenario Automations and email notifications should all be turned off in Admin → Workflows before you import, or every imported ticket will fire its full automation chain at customers.
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 helpdesk. Train agents on Freshdesk ticket-handling and rebuilt macros before go-live, not after. A typical Freshdesk migration runs roughly 2,000 tickets per hour through managed-migration tools, so plan the cutover window against total ticket count.
Import mechanisms: UI wizard, CSV, and managed-migration tools
The load paths in, each with different limits and shapes. Picking the wrong one is how mid-migrations stall at scale.
Freshdesk exposes several load paths and the right one depends on dataset size, object mix, and whether you need to re-run idempotently. The native CSV importer covers Contacts and Companies through the UI. Tickets, conversations and attachments come in through managed-migration tools that sit on top of Freshdesk and add staging, transformation and dedup layers.
UI Import — Contacts and Companies
The native import lives under Admin → Customers → Contacts (or Companies) → Import9. It accepts CSV with headers that the importer auto-maps to Freshdesk fields; you can also manually adjust the mapping if column names diverge from field names8. Existing contacts matched on email are overwritten by import rows, so backups before re-importing are essential.
Limits on the native CSV path are modest: the importer does not publish a hard per-file row cap but practical experience and the Freshworks marketplace Import app exist precisely because the native flow becomes unwieldy past a few thousand rows5. Tickets are not importable through the native UI — they must come in via a managed-migration tool.
Third-party and managed-migration tools
Several specialist managed-migration apps live on the Freshworks Marketplace, alongside generic iPaaS tools like Airbyte and Fivetran529. For one-time migrations from sources such as Zendesk, Intercom, Help Scout, Jira Service Management or shared inboxes, these tools handle ticket-by-ticket loading, conversation threading, attachment transfer and delta sync after the initial load.
For ongoing syncs (the post-migration phase), Airbyte and Fivetran become the system of integration — Airbyte's open-source Freshdesk connector lands ticket and contact data into a warehouse for analytics, and reverse-ETL flows write enrichment back into Freshdesk.
Mapping your data into Freshdesk
The longest section — because field mapping is where almost every migration that fails actually breaks.
Mapping is where every helpdesk migration earns its scars. The schema decisions you make in your mapping spreadsheet determine whether agents can find historical tickets on day two, whether SLAs fire correctly on day five, and whether reporting trusts the data on day thirty.
Work object by object, top to bottom of the import order: Agents and Groups first (so tickets can be assigned), then Companies (so contacts can be associated), then Contacts, then Tickets and their conversation threads, then Solutions (KB), and finally Custom Object records.
Contacts and Companies
| Source | Destination | Note |
|---|---|---|
| email (unique identifier) | Lowercased on import; upsert key by default — match overwrites9 | |
| secondary emails | secondary_emails (up to 9) | One contact can hold 10 emails total9 |
| first / last name | name | Freshdesk stores a single name field; concatenate on the source side |
| phone | phone | Normalise to E.164 with country code (+14088481234) so the phone channel can match9 |
| company | company_id (lookup) or company_name | Import companies first; contacts resolve to the most recent matching company name |
| view all company tickets flag | view_all_tickets | Set during import or contact cannot see organisation-level ticket lists9 |
| language | language | Two-letter code; defaults to account language if missing |
| time zone | time_zone | Use the IANA format Freshdesk expects (America/Los_Angeles) |
Tickets, conversations and threads
Tickets are the centre of gravity. Each carries a requester, subject, description (first message body), status, priority and source channel — the source value (email, portal, phone, chat, feedback widget, outbound) drives Source-based reports.
Conversations on a ticket come in two flavours: public notes (visible to the requester) and private notes (internal-only). Both carry author, body, timestamp and optional attachments. The migration pattern: create the ticket with the description as the first message, then load remaining conversation entries as notes (private and public agent notes) and replies (outbound public agent replies). Backdating created_at on each note keeps the thread chronological rather than collapsing to import-day21.
| Source | Destination | Note |
|---|---|---|
| ticket_id / case_number | Custom number field: legacy_ticket_id | Freshdesk assigns its own sequential ID — store the source ID in a custom field for reconciliation |
| subject / title | subject | Required |
| first message body | description | HTML accepted; inline images need attachment re-upload |
| requester email | email or requester_id | Import contact first; use email if contact already exists |
| status | status (numeric: 2=Open, 3=Pending, 4=Resolved, 5=Closed) | Map source statuses to the integer codes Freshdesk expects19 |
| priority | priority (numeric: 1=Low, 2=Medium, 3=High, 4=Urgent) | Same integer-code mapping; defaults to Low if missing |
| channel / source | source (numeric: 1=Email, 2=Portal, 3=Phone, 7=Chat, 9=Feedback widget, 10=Outbound) | Drives Source reports — get this right or your channel mix breaks |
| assigned agent | responder_id (or email) | Agent must exist in Freshdesk at import time or ticket lands unassigned |
| group | group_id | Group must exist; otherwise ticket falls into default group |
| tags | tags (array) | Free-form strings; tag spillover is a common cleanup issue post-migration |
Solutions (knowledge base)
Freshdesk's knowledge base is Solutions, a three-level hierarchy: Category → Folder → Article. Categories group folders (often by product or audience), folders group articles, and articles carry title, HTML body, status (draft/published) and visibility (public/logged-in/agents-only).
Import KB content top-down: categories first, then folders inside each category, then articles inside each folder. Translations are imported separately per article per language code and require the article to exist in the primary language first. Inline images in article HTML must be re-uploaded as attachments — source URLs that point at the old platform's CDN will break.
Automation rebuild — Dispatch'r, Observer, Supervisor, Scenario Automations
Freshdesk has three automation engines and none of them import — they are rebuilt by hand in Admin → Workflows. Dispatch'r fires on ticket creation (events like a new email arriving). Observer fires on ticket update (events like status changes or note additions). Supervisor is time-based and runs hourly across the helpdesk — useful for SLA escalations and stale-ticket nudges20.
Scenario Automations (Freshdesk's equivalent of macros) are agent-invoked bundles of actions and likewise rebuild-only. Document every source rule with its trigger conditions and actions, group them by engine type, and rebuild in priority order — Dispatch'r first because it shapes incoming tickets, then Observer for in-flight updates, then Supervisor for time-based housekeeping, then Scenario Automations once agents start working in the system.
SLA policies, business hours and CSAT
SLA policies are configured under Admin → Workflows → SLA Policies and combine a business-hours calendar (working days and times), a set of priority-based response and resolution targets, and an escalation chain. SLA policies do not import — recreate every policy with its priority-level targets, link each to the right business-hours calendar, and assign products or groups as scoping conditions20.
CSAT ratings live on resolved tickets. Historical CSAT scores can be loaded onto migrated tickets through a managed-migration tool — this is optional and only worth doing if you need year-over-year CSAT trend reporting in Freshdesk Analytics. New CSAT surveys post-go-live are sent automatically on ticket resolution based on the survey configuration in Admin → Customer Satisfaction.
Multi-channel inbox setup
Channel configuration is entirely UI-driven and must happen after the data import and before go-live. Email requires connecting each support address under Admin → Channels → Email with SPF/DKIM verification and forwarding from the source provider. Phone is a Freshcaller number; chat enables Freshchat; social connects Twitter, Facebook or Instagram; WhatsApp/SMS through the WhatsApp Business or SMS channel apps.
Do not enable email forwarding from production support inboxes until after the import window closes — otherwise every email forwarded during the migration creates a duplicate ticket against the contact you just imported21.
Files and attachments
Attachments on tickets are capped at 20 MB per conversation on paid plans (15 MB on legacy Sprout / trial accounts)23. Larger files use the Dropbox or OneDrive integration to hotlink rather than uploading directly. During migration, attachments are downloaded from the source as binaries and re-uploaded into Freshdesk attached to the migrated ticket or note.
Attachments count against the account's overall storage allowance, which is tier-dependent. For large estates, the common pattern is: re-upload only attachments newer than 12 months, and store deep links to S3 or the original provider in a custom URL property on older tickets.
Audit trail, ownership and original timestamps
created_at and updated_at are managed by Freshdesk — but Freshdesk allows backdating created_at on tickets during import so the timeline shows the original date21. Freshdesk stamps the import day on most updates but preserves the original created_at, which means a first_responded_at that predates created_at is possible and benign24.
Agent assignment during import works only if the agent email exists at the moment of import; rows whose responder_id cannot be resolved are imported with no agent set, which silently breaks downstream agent-based reporting. The audit log under Admin → Account → Audit Log tracks configuration changes (agent creation, automation edits, KB edits) but not granular per-field changes on individual tickets25.
The pitfalls that derail Freshdesk migrations
Nine specific failure modes — ranked by impact, each tied to the exact Freshdesk 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 agents being allowed in. The reliable pattern is a three-stage approach: a demo / sample load of about 100 random tickets with stakeholder spot-checks, the full load with real-time monitoring of record counts and error rates, then a delta migration that captures everything that changed in the source during the full load.
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 agents get login access.
- Total tickets imported vs source — minus deliberately excluded rows (spam, test tickets, rows older than the agreed history horizon).
- Tickets per status (Open, Pending, Resolved, Closed) vs source — a non-trivial mismatch usually signals a status integer-code mapping error.
- Tickets per priority and per source channel vs source — confirms the priority and source integer-code mappings round-tripped correctly.
- Conversation count per ticket for a 100-ticket sample vs source — confirms public and private notes attached to the right parent.
- Total contacts and companies imported vs source — checking that email-based collapse did not over-merge two distinct people sharing an inbox.
- Attachments per ticket for a 50-ticket sample — confirms the binary re-upload completed and inline images render.
- Solutions categories, folders and articles counted by hierarchy — confirms the KB tree round-tripped.
- Agent and group assignments —
GROUP BY responder_idand confirm no ticket landed unassigned that should not have. - CSAT scores if historical Satisfaction Ratings were loaded — confirms historical scores attached to the right tickets.
On top of reconciliation, run a manual spot-check: pick 30 random tickets across statuses and verify each against the source UI — subject, body, full conversation thread, attachments, requester, agent, status, tags. Pick five VIP tickets and trace the full conversation graph. If three or more of the 30 show non-trivial discrepancies, halt the load, fix the root cause, and re-import affected tickets by source ID.
Freshdesk does not have a native bulk-undo for imports. The real rollback strategy is: export every record to a tagged S3 bucket before the import starts, stamp every imported ticket with a migration_batch_id custom field, and if catastrophe strikes, bulk-delete by that batch ID and re-import from the cleaned source. Soft-deleted tickets in Freshdesk's trash retain for 30 days, providing a brief recovery window for accidental deletions25.
Cutover sequencing: (1) source goes read-only; (2) final delta export captures everything that changed during the test-import window; (3) delta is imported via the same loader; (4) reconciliation runs; (5) email forwarding repoints from source to Freshdesk support addresses; (6) automations and email notifications re-enable; (7) agents get login access and a 48-hour hyper-care window; (8) source decommission is scheduled 30 to 90 days out.
Migration partners and tools
Freshworks Marketplace apps, managed-migration vendors and iPaaS — what each is good for and how to choose.
The Freshworks ecosystem has a smaller set of specialist migration vendors than Zendesk or Salesforce, but the tools that exist are mature. Wizard-driven managed-migration apps on the Freshworks Marketplace install into your Freshdesk account and walk through field mapping in a UI529 — covering Zendesk, Intercom, Help Scout, Jira Service Management, ServiceNow, Gorgias and shared inboxes as common sources.
A second band of long-running managed-migration vendors in the Freshdesk corner offers free sample migrations of around 100 tickets with associated organisations and contacts, then quotes the full migration based on record count and complexity. These tools handle ticket-by-ticket loading, conversation threading, attachment transfer and a follow-up delta migration to catch records that changed during the main load.
On the ETL and iPaaS side, Airbyte and Fivetran both have Freshdesk connectors. Their role in a migration is rarely the migration itself — it is the staging layer that lands source data into a warehouse, the transformation layer that converts dropdown values and resolves agent IDs in SQL, and the ongoing-sync layer that takes over once the one-time migration is complete. Workato and Tray.io are common picks where the migration is bundled with workflow-automation rebuilds.
Managed-migration cost ranges vary widely. A clean Zendesk-to-Freshdesk move under 25,000 tickets with standard fields and no Solutions content often lands in the $1,500–$5,000 range. Larger migrations with full conversation history, attachments, KB content and SLA / automation rebuild typically run $5,000–$25,000, driven by ticket count, custom-field complexity, historical depth and the integrations that need rebuilding rather than re-pointed29.
For teams that want to outsource the migration end-to-end, FlitStack specialises in Freshdesk migrations and handles the field mapping, ticket-history preservation, Dispatch'r / Observer / Supervisor rebuild, Solutions KB import and validation work described in Sections 5 and 7 of this guide. Pricing is fixed-fee, based on ticket count and source platform, with separate line items for Custom Objects and SLA / automation rebuild 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 Marketplace app they can drive themselves, a managed vendor handling the full project, an iPaaS-first approach, or a specialist migration partner. [Explore FlitStack →](/contact)




