If you are planning to migrate into Freshdesk, slow down before you start exporting data.
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. Teams that respect that structure end up with calm migrations. Teams that do not usually spend weeks cleaning things up after go live.
This checklist is written from the perspective of someone who has migrated thousands of tickets into Freshdesk across dozens of accounts. It focuses on what actually matters, what Freshdesk handles well, and where teams usually get surprised.
Scope the migration
This step decides whether your migration feels controlled or chaotic. Do not rush it.
Start by agreeing on how much history you really need. Freshdesk can handle large volumes, but very old tickets often add little operational value. Two to five years is common. Full history is possible if you plan for it.
Identify every agent that appears on historical tickets. Active agents matter, but legacy agents matter too. If a name appears in ticket history, that agent must exist in Freshdesk or be mapped to a placeholder user.
Decide what you are migrating.
Tickets, conversations, notes, replies, attachments, contacts, companies, tags, custom fields, SLA data, satisfaction ratings. Write this list down.
Then decide what you will not migrate. Spam. Test tickets. Auto generated noise. Deprecated fields. Old views nobody uses anymore.
Finally, map your old system to Freshdesk’s model. Statuses, priorities, groups, agents, ticket types, custom fields. This mapping document becomes your anchor during implementation and validation.
How Freshdesk models data
Understanding Freshdesk’s data model prevents most mistakes.
A ticket is the core object. Each ticket contains conversations. Conversations include customer replies, agent replies, and private notes.
Contacts represent customers. Agents are separate user records with roles and permissions.
Groups control ownership and routing. A ticket always belongs to a group, even if it is also assigned to an agent.
Custom fields exist at the ticket and contact level, but they must be created before you can populate them via API or import.
Once you internalise this structure, the rest of the migration becomes predictable.
What can be migrated into Freshdesk via API and imports
Freshdesk offers both API based creation and bulk CSV imports. In practice, large migrations usually combine both.
Contacts
Contacts can be imported in bulk using the Contacts Import API or CSV imports. At minimum, each contact needs a name and either an email or phone number.
You can preserve legacy IDs, account attributes, and segmentation data using custom contact fields, as long as those fields exist before import.
Deduplication is handled primarily by email address. If your source system allows multiple emails per contact, plan how you will flatten or prioritise them.
Tickets and conversations
Tickets can be recreated through the Tickets API. Each historical ticket becomes a Freshdesk ticket with:
- Subject
- Description or first message
- Status and priority
- Group and agent assignment
- Creation and resolution timestamps
Replies and notes are added as ticket conversations. Private notes map cleanly to internal notes in Freshdesk.
Timestamps can be preserved, but you must explicitly pass them during creation. If you skip this, Freshdesk will default to the import time.
Attachments
Attachments are supported on both ticket creation and conversation replies. File size limits apply and should be tested early.
Inline images and long email threads are common failure points. Always validate the largest attachments from your source system before running a full import.
Custom fields
Ticket and contact custom fields can be populated via API or import, but only if they already exist in the Freshdesk UI.
This is non negotiable. Missing fields result in silent data loss or failed imports.
Agents, groups, and assignment
Agents must be created manually in the UI. The API can reference agents by ID, but cannot create them.
Groups must also be created ahead of time. Once they exist, tickets can be assigned correctly during import.
Ownership accuracy depends entirely on this preparation.
Satisfaction ratings
Freshdesk allows importing CSAT data through the Satisfaction Ratings API. This is optional, but valuable if historical reporting matters.
What must be configured in the Freshdesk UI
This is where many migrations stumble.
Email channels and support addresses must be connected manually. Forwarding, DNS verification, and channel configuration all live in the UI.
Agents, roles, and permissions are UI only. Decide who is an admin, who is an agent, and who needs limited access.
Groups and routing rules are also configured manually. Automations, dispatch rules, supervisor rules, and SLA policies must be recreated in the interface.
Canned responses, scenario automations, and email templates cannot be imported via API. Plan time to rebuild them.
If you use the Freshdesk portal or knowledge base, structure, categories, branding, and URLs are also manual steps.
Pre migration setup in Freshdesk
This phase determines how smooth your import will be.
Create the Freshdesk account and confirm region, timezone, and plan. These choices affect API behaviour and feature availability.
Create all agents, including inactive or legacy ones needed for ticket ownership.
Create all groups and confirm which agents belong to each group.
Recreate ticket and contact custom fields. Use clear internal names. Lock the schema before importing data.
Disable automations, dispatch rules, SLAs, and notifications. You do not want Freshdesk reacting to historical data.
Generate API keys and test access limits. Freshdesk enforces rate limits and pagination. Your migration scripts must respect both.
Run a pilot import. A few dozen contacts and tickets is enough to reveal mapping errors.
Migration execution
Start with contacts. Validate deduplication, field mapping, and search behaviour.
Then migrate tickets in batches. Import the oldest data first so newer tickets remain untouched until delta runs.
For each ticket, confirm:
- Correct requester
- Correct group and agent
- Correct status and priority
- Full conversation history in order
- Attachments open correctly
Monitor API responses carefully. Log failures. Retry with backoff when rate limits are hit.
Once the main import is complete, run a delta import for tickets created after your initial export cutoff.
Only after validation should you switch email forwarding and live traffic to Freshdesk.
Post migration checklist
Compare counts. Tickets, contacts, attachments, agents, groups.
Open tickets from different years and different teams. Look for missing replies, broken threading, or incorrect ownership.
Test inbound email. Reply from Freshdesk. Confirm replies thread correctly.
Gradually re enable automations, SLAs, and notifications. One at a time.
Have agents test real workflows. Assignments, notes, status changes, internal collaboration.
Schedule a review after one week and again after one month. This is where small gaps surface.
Common mistakes and hard earned lessons
Custom fields created too late cause silent data loss. Always build schema first.
Leaving automations on during import floods agents and customers.
Agent mapping errors are painful to fix after the fact. Double check IDs.
Large attachments fail quietly if you do not test them early.
Freshdesk is easy to use, but different from many legacy tools. Short training sessions prevent long term friction.
Keep the old system available in read only mode for a short period. It gives your team confidence and a safety net.
A Freshdesk migration done well feels boring. That is the goal.