The Complete Guide to Migrating from Freshdesk to Kustomer

Moving from Freshdesk to Kustomer is a significant step toward a more unified, customer centric support experience.

This guide covers the essential steps, API specifics, field mappings, known failure modes, and cutover validation you need to move your data cleanly between these two platforms.

Defining Your Migration Scope

Before you begin moving data, you need to understand which parts of your Freshdesk instance can be automated and which require a personal touch.

What to Migrate via the API

Most of your core data has a direct path from Freshdesk to Kustomer. This includes the essential building blocks like agents, groups, companies, and contacts.

Your historical data, such as tickets and their full conversation threads, can also be moved automatically.

This category also covers your self service content, specifically solution articles and canned responses, which find new homes in Kustomer's knowledge base and shortcuts sections.

What to Configure Manually

Certain elements of Freshdesk are tied to specific settings that do not have a direct data link. You will need to manually recreate your ticket forms within Kustomer's settings to ensure your data collection remains consistent.

Specific roles and their associated permission sets also require manual setup to ensure your team members have the correct level of access in the new environment.

Finally, the actual logic of your assignment rules and skills must be rebuilt to fit Kustomer's routing engine.

What to Archive

Migration is a perfect time to clean up your database. Freshdesk automatically archives tickets that have been closed and inactive for 120 days to improve performance. You should identify similar old data that is no longer needed for daily operations.

If you have forum threads or old discussions that aren't critical for live support, you might choose to archive them into custom objects for reference rather than cluttering your new conversation timeline.

Preparing Kustomer for Data Import

To ensure the data you are moving has a place to land, several configurations must be built in Kustomer before you start the import.

• Define Custom Attributes and Klasses: You must create the data schema in Kustomer first so that custom fields from Freshdesk have a corresponding destination.
• Establish Teams and Users: Replicate your Freshdesk groups as Kustomer Teams and ensure all agents are invited as Users.
• Set Up Business Schedules: Define your support hours in Kustomer to ensure your reporting and SLA calculations remain accurate.
• Create SLA Policies: Rebuild your service level standards in Kustomer to match the expectations you set in Freshdesk.
• Build Knowledge Base Structure: Set up the categories and folders in Kustomer so your solution articles have an organized hierarchy to populate.

Migrating Your Objects

Data Mapping

Object-Level Mapping

Field-Level Mapping Notes

Object-level mapping tells you where things land. Field-level mapping is where migrations actually break. Key notes:

• Priority: Freshdesk's priority field (integer: 1=Low, 2=Medium, 3=High, 4=Urgent) does not map to a native Kustomer conversation field. It must be pre-created as a custom attribute on the Conversation Klass (e.g., customAttributes.priority, type: string or integer) before any conversations are imported.
• Tags: Freshdesk ticket tags map to Kustomer conversation tags and are generally portable as-is, but must be passed as an array of strings in the API payload.
• Ticket Source: Freshdesk tracks the channel a ticket originated from (email, phone, chat, portal, etc.) as the source integer field. Kustomer tracks channel via the channel field on Messages. You must map Freshdesk source integers to Kustomer channel strings (e.g., 1 → "email", 2 → "portal") during transformation.
• Custom Fields: Any Freshdesk ticket custom field must be pre-created as a Klass attribute in Kustomer before import. The attribute name in Kustomer must be explicitly mapped to the Freshdesk field key in your transformation layer.
• Agent/Contact Identity: Freshdesk agent email is the reliable join key to Kustomer User email. For contacts, use email as the unique identifier — but see the deduplication notes below.

Identity Deduplication

The guide to using unique identifiers like email addresses is the starting point, not the full answer. Specific cases to handle before import:

• Contacts with multiple emails: Freshdesk allows one email per contact. Kustomer supports multiple email addresses on a Customer record. If a contact appears in Freshdesk under multiple accounts with different emails, resolve the canonical record before migrating — do not rely on the import to merge them.
• Duplicate contacts: Run a deduplication pass on your Freshdesk contact export before import. Filter by email using a script or spreadsheet. Kustomer's API does not automatically merge records on conflict — a second POST /customers with the same email will return a 422 error rather than silently merging.
• Deleted agents: Tickets assigned to deleted Freshdesk agents will have a null or stale responder_id. Map these to a placeholder or admin user in Kustomer before import, or the conversation will import without an assignee.

Migration Sequence

The actual movement of data must follow a logical sequence to maintain relationships between different pieces of information. For example, a ticket cannot be assigned to a customer who does not exist yet.

The first step is moving your Users and Teams. Freshdesk agents become Kustomer Users, and your groups are transformed into Teams.

Once your staff structure is in place, move your Companies. This allows you to associate customers with their organizations right from the start.

Next, migrate your Customers. Freshdesk contacts map directly to Kustomer Customers. Use email addresses as the unique join key. Resolve duplicates before this step, not during.

After your customers are settled, you can bring over your Knowledge Base Articles and Shortcuts. Freshdesk solution articles move into KB articles, while canned responses become shortcuts.

The most complex part of the process is the migration of Conversations and Messages. Freshdesk tickets are converted into Kustomer conversations.

Within these, ticket replies are migrated as Messages, while both private and public notes from Freshdesk are moved into Kustomer's internal Notes object.

If these communications have Attachments, they are created and linked to the specific message or note they belong to. Finally, you can migrate historical Satisfaction Responses to preserve your customer feedback history.

Post Migration Configuration

Once the bulk of your data is in the system, you must rebuild the automation and routing logic that makes your team efficient.

• Rebuild Workflows: Freshdesk automation rules for ticket creation, updates, and hourly triggers must be manually remapped into Kustomer's Workflow engine.
• Configure Queues and Routing Rules: Recreate your assignment logic to ensure conversations are automatically directed to the right teams.
• Set Up Sub Statuses: If you used custom ticket statuses in Freshdesk, you will need to manually configure Sub Statuses in Kustomer to match that workflow.
• Verify Knowledge Base Themes: Ensure your public facing knowledge base looks correct by reviewing your migrated content within Kustomer's theme editor.

Insider Secrets

1. Bypass Rate Limits with importedAt: Kustomer allows a special privilege for migration workloads. If you include an importedAt timestamp in your API request body, those calls are generally not subject to the standard rate limits. The field goes in the top-level payload of your conversation or message POST request:

{
  "importedAt": "2023-06-15T10:30:00.000Z",
  "createdAt": "2023-06-15T10:30:00.000Z",
  "channels": [{ "type": "email" }]
}

Without importedAt, large-volume imports will hit standard rate limits quickly. Confirm with Kustomer support whether this exemption requires activation on your specific account before you begin.

2. Order of Creation for Attachments: You cannot upload an attachment in a vacuum. You must first create the message or note it belongs to, and then use that specific ID to link the file.

3. Preserving Your Timeline: To keep your migration from looking like everything happened today, Kustomer allows administrators to manually set createdAt and modifiedAt values for messages and conversations. Pass these as ISO 8601 timestamps in your POST body. This ensures your historical timeline remains accurate.

4. Custom Objects for Time Entries: Kustomer doesn't have a built in "Time Entry" object like Freshdesk does. The correct approach is to create a custom Klass specifically for time logs and link each record to its respective conversation via the conversation ID.

5. Sequential KB Migration: When moving your knowledge base, you must create your Categories and Folders first. Articles require a folderId or categoryId upon creation, so the structure must exist before the content can be placed.

6. Deep Pagination Warnings: When exporting data from Freshdesk, avoid requesting page numbers over 500. The Freshdesk API uses page-based pagination (?page=N&per_page=100). Requests beyond page 500 are performance intensive and can lead to extremely slow response times or timeouts. For large datasets, filter by date range to stay within safe page boundaries instead of paginating sequentially through the full dataset.

Known Failure Modes

Every migration has edge cases that don't appear in the happy path. These are the ones most likely to cause silent data loss or post-migration cleanup work on a Freshdesk-to-Kustomer move:

• Merged tickets: Freshdesk allows tickets to be merged. The child ticket is closed; only the parent survives in active views. When you export, you will likely pull both. Decide in advance whether you migrate both records or only the parent, and how to represent the merge relationship in Kustomer (e.g., a note on the conversation).
• Multi-channel ticket sources: Freshdesk consolidates email, phone, chat, and portal tickets into a single ticket model. Kustomer tracks channel at the message level. If you migrate without mapping the source field, all conversations will appear as the same channel type. Run a frequency count on source values in your export before you write your transformation.
• Tickets with deleted agents: As noted above, responder_id will be null or unresolvable. Import will succeed but the conversation will be unassigned. Build a fallback assignment rule or a placeholder user before you start.
• Attachments on deleted tickets: If a ticket was soft-deleted in Freshdesk but still appears in your export, its attachments may return 404s when you try to re-download them during migration. Validate attachment URLs before the migration run, not after.
• Custom field type mismatches: A Freshdesk dropdown field exported as a string will fail to import if the corresponding Kustomer Klass attribute is typed as integer. Audit your custom field types in both systems before building your transformation layer.

Cutover and Validation

A migration is not complete when the import finishes. It is complete when you can verify the data is correct.

Pre-Cutover Checklist

• Run a full export of your Freshdesk data and store a local copy. This is your rollback baseline.
• Perform a test migration on a sample of 500–1,000 tickets before the full run. Spot-check 20–30 records manually.
• Confirm the importedAt exemption is active on your Kustomer account.
• Validate all custom Klass attributes exist in Kustomer and types match your Freshdesk field types.

Post-Migration Validation

• Record counts: Compare total ticket count from Freshdesk's API (GET /api/v2/tickets?page=1&per_page=1, check the X-Total-Count header or equivalent) against total conversation count in Kustomer. A mismatch means something did not import.
• Spot checks: Pull 20–30 tickets at random from your Freshdesk export. Verify each one exists in Kustomer with the correct customer association, message thread, attachments, and custom field values.
• Timestamp audit: Verify that createdAt on imported conversations matches the original Freshdesk ticket created_at. If timestamps defaulted to today, the createdAt override was not applied correctly.
• Attachment audit: Check a sample of conversations with attachments. Confirm the files are accessible and linked to the correct message.
• Agent assignment audit: Query Kustomer for conversations with no assignee. If the count is unexpectedly high, trace back to deleted-agent records in the source data.

Rollback Plan

If validation fails materially, the cleanest rollback is to delete the Kustomer conversations created during the failed run and re-import from your Freshdesk baseline export. Kustomer does not have a native bulk-delete UI for conversations; you will need to use the DELETE /conversations/{id} endpoint in a script. Keep a log of all conversation IDs created during the import run so you can target them precisely.

Summary

The core of a successful Freshdesk-to-Kustomer migration is sequencing, field-level preparation, and validation — not just moving records across. Get your Klass attributes defined before you import, use importedAt to avoid rate limit collisions, map your ticket source fields explicitly, and validate record counts and timestamps before you call the migration done.

Rebuilding automation logic requires manual effort, but it also gives you a chance to tighten your routing rules in Kustomer's workflow engine rather than carrying over legacy configuration unchanged.

If you'd rather focus on your revenue instead of wrestling with mapping sheets and pagination loops, ClonePartner can handle the full migration for you. Every project gets a dedicated engineer who understands the nuances of both APIs and ensures zero downtime.

Further Reading:

• Kustomer
• Freshdesk