Freshdesk Migration Checklist

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 (reply type), agent replies (reply type with agent as responder), and private notes (note type with private: true). These map to different API calls: ticket creation uses POST /api/v2/tickets, while replies and notes are added via POST /api/v2/tickets/{id}/reply and POST /api/v2/tickets/{id}/notes respectively. The ticket creation API and the conversation API are separate — a common source of confusion in migration scripts.

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. The choice matters — they are not equivalent.

Capability	API import	CSV import
Ticket conversations / replies	✅ Full support	❌ Not supported
Timestamp preservation	✅ Explicit fields required	⚠️ Limited, often defaults to import time
Attachments	✅ Supported	⚠️ Limited support
Custom field population	✅ Supported	✅ Supported
Contact upsert / deduplication	✅ Via POST /api/v2/contacts/upsert	✅ Via CSV upload
CSAT / satisfaction ratings	✅ Via Satisfaction Ratings API	❌ Not supported
Volume throughput	⚠️ Rate-limited	✅ Better for large contact lists

In practice, large migrations usually combine both: CSV for bulk contact seeding, API for tickets and conversations.

API rate limits

Freshdesk enforces rate limits per plan. On the Growth plan, the limit is typically 1,000 API requests per hour. Enterprise plans have higher limits. Rate limit headers are returned with every response — your migration scripts must read them and implement exponential backoff. Pagination is page-based with a maximum of 100 records per page.

Contacts

Contacts can be imported in bulk using POST /api/v2/contacts/upsert 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 by email address using exact match (case-insensitive). Phone-only contacts do not deduplicate against existing records — if you have contacts with no email address, expect duplicates unless you handle them explicitly before import.

Tickets and conversations

Tickets are created via POST /api/v2/tickets. 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 via separate API calls. Private notes map cleanly to internal notes in Freshdesk.

Timestamp preservation requires explicitly passing the following fields during creation: created_at, updated_at, fr_due_by (first response due), and due_by (resolution due). If you omit these, Freshdesk defaults to the import timestamp — your historical timeline will be wrong and cannot easily be corrected after the fact.

Attachments

Attachments are supported on both ticket creation and conversation replies. The maximum attachment size is 20MB per file. 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. Lock the schema before you begin any data loading.

Agents, groups, and assignment

Agents can be created via POST /api/v2/agents on supported plans, but in practice most teams create agents manually in the UI to control role assignment, permission levels, and license allocation. Whether the API or UI is used, agents must exist before any ticket import references their ID — referencing a non-existent agent ID will cause silent assignment failures.

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. Availability depends on your plan — verify that CSAT is enabled before building import logic for it. This step 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 require UI configuration to control access levels correctly. 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.

Note: some features — including sandbox environments and certain custom role configurations — are plan-gated. Confirm what is available on your specific plan before designing your setup sequence.

Pre migration setup in Freshdesk

This phase determines how smooth your import will be.

Create the Freshdesk account and confirm region, timezone, and plan. Freshdesk operates separate data residency regions (US, EU, AU) and the API base URL differs per region — use the correct base URL for your account or all API calls will fail silently or return auth errors.

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 against your plan's rate limits. Your migration scripts must respect both rate limits and page size maximums (100 records per page).

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.

Delta migration

Once the main import is complete, you need to capture tickets created or updated after your initial export cutover. Use the updated_at field to identify records changed since your cutover timestamp — not ticket ID range, which does not account for edits to older tickets. Query your source system for all records where updated_at > [cutover_time] and re-import them.

Be aware of the race condition: during the window between your final export and switching live traffic to Freshdesk, new tickets will continue arriving in the old system. Your delta logic must account for this window. Keep the old system in read-only mode (do not disable it) until the delta import is validated.

Only after validation should you switch email forwarding and live traffic to Freshdesk.

Failure taxonomy

Most migration failures fall into predictable categories. Silent failures are the most dangerous because they do not surface until a customer or agent notices missing data.

Failure type	Symptom	Root cause	Detection method	Fix
Silent field loss	Tickets missing custom field values	Field did not exist in Freshdesk at import time	Compare source field count vs. Freshdesk field count per ticket	Create fields first; re-import affected records
Timestamp defaulting	All tickets show import date, not original date	created_at / updated_at not passed in API payload	Spot-check 10 tickets across date ranges	Re-import with correct timestamp fields
Attachment failure	Ticket has no attachment despite source having one	File exceeds 20MB limit, or inline image encoding issue	Check import logs for 4xx on attachment endpoints	Strip oversized files; re-encode inline images as links
Rate limit failure	Partial imports, intermittent 429 errors	Script not reading rate limit headers	Monitor response headers; track 429 frequency	Implement exponential backoff; reduce concurrency
Agent assignment failure	Tickets assigned to wrong agent or unassigned	Agent ID in payload does not match Freshdesk agent ID	Cross-reference agent ID map after import	Rebuild agent ID mapping; bulk-update affected tickets
Conversation ordering	Replies appear out of sequence	Conversations imported without respecting created_at ordering	Open a threaded ticket and verify reply order	Re-import conversations in chronological order
Contact deduplication failure	Duplicate contacts created	Source contact had phone only, no email	Run deduplication report post-import	Merge duplicates via UI or API; add email to contacts where possible

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. The 20MB per file limit catches teams who have never audited their attachment sizes.

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 — and you will need it for delta migration validation.

A Freshdesk migration done well feels boring. That is the goal.