Freshdesk to Zendesk Migration: API Limits, Mapping & Methods

Migrating from Freshdesk to Zendesk is a data-model translation problem, not a drag-and-drop. Every migration carries a hidden risk: the silent loss of historical context. It rarely looks like a total failure — it looks like a successful import where 10% of your conversation threads, inline images, or attachment histories are quietly missing.

Freshdesk organizes support around contacts and tickets in a relatively flat hierarchy. Zendesk organizes everything around users, organizations, and tickets — a layered model where every record relates to others through explicit ID references. Every contact, conversation, attachment, and custom field value must be extracted from one structure and written into the other. The structural gaps between them are where data silently disappears.

This guide covers the exact API constraints on both sides, complete field-mapping tables, attachment and inline-image handling, and a direct comparison of migration methods — so you can pick the approach that matches your volume, timeline, and risk tolerance.

For a deeper look at exporting your data before migration, see How to Export Data from Freshdesk: Methods, API Limits & Mapping. If identity mapping is the riskiest part of your account, read How to Migrate Users & Organizations Without Breaking History.

Freshdesk to Zendesk Migration: Why the Data Model Matters

Freshdesk's data model is contact-centric and flat. A contact submits a ticket. That ticket has conversations (replies, notes, forwards), each with optional attachments. Contacts can belong to companies, but companies are loosely coupled — they exist mainly for grouping and reporting. There is no mandatory hierarchy between contacts, companies, and tickets.

Zendesk's data model is ticket-centric and layered. A ticket has a requester (user), belongs to an organization, is assigned to a group and an agent, and contains a flat list of comments — each marked public or private. Organizations in Zendesk are first-class objects with their own domain mapping, shared ticket access rules, and tag inheritance. Users must exist before tickets can reference them. (developers.freshdesk.com)

This structural mismatch creates three problems every migration must solve:

1. Contact → User + Organization split. A single Freshdesk contact with a company association must be written as a Zendesk user and an organization membership. If you skip the organization step, you lose the company association — and any Zendesk automations built around organizations will not work. Freshdesk's view_all_tickets permission on contacts does not have a direct Zendesk equivalent; Zendesk handles organization-level ticket visibility through user restrictions and organization-level settings, not a single boolean.

2. Conversation → Comment translation. Freshdesk conversations have discrete types: replies, notes, and forwards. Zendesk comments are a flat list with a public boolean. Replies map to public comments; notes map to private comments. Forward threads have no direct equivalent — they must be appended as private notes or the context is lost.

3. Status mapping is not 1:1. Freshdesk uses four statuses by default (Open, Pending, Resolved, Closed) plus custom statuses. Zendesk uses six (New, Open, Pending, On-hold, Solved, Closed). You need an explicit mapping table before you write a single line of migration code.

Practical rule: create Zendesk organizations first, then users, then tickets. If you import tickets before the user and organization membership exist, you lose clean account context in the target. This import order matters even more if Freshdesk relied on view_all_tickets, because Zendesk handles that visibility through a combination of user restrictions and organization-level settings rather than one boolean on the contact. (developers.freshdesk.com)

For a detailed walkthrough on handling the user/organization relationship, see How to Migrate Users & Organizations Without Breaking History.

Freshdesk Export Constraints: API Rate Limits and Extraction Traps

Freshdesk's v2 REST API is the only reliable way to extract tickets with full conversation history, attachments, and custom field values. The built-in CSV export does not include conversation content or archived tickets. (developers.freshdesk.com)

Rate limits by plan

Freshdesk enforces per-minute, account-wide rate limits based on your plan tier:

These limits are account-wide — every app, integration, webhook handler, and migration script shares the same pool. If your production Freshdesk instance is running marketplace apps or automation integrations during the export, those requests eat into your migration budget. Endpoint-specific caps on Tickets List and Contacts List can reduce practical throughput further, and include=requester or include=description consumes extra credits per call. (support.freshdesk.com)

The 30-day default trap

By default, GET /api/v2/tickets only returns tickets created in the last 30 days. For older data you must use the updated_since parameter. Even then, the endpoint is capped at 300 pages. Pagination defaults to 30 records per page and tops out at 100 per page. (developers.freshdesk.com)

The filter/search endpoint (/api/v2/search/tickets) has a harder limit: it returns a maximum of 30 results per page and caps at 10 pages — a hard ceiling of 300 tickets per search query. To work around this, split searches by date range or other criteria to keep result sets under 300.

Conversation pagination

View a Ticket?include=conversations only returns up to ten conversations. Tickets with longer threads require a separate call to the List All Conversations endpoint. This means ticket-count parity alone is not enough — you need conversation-count parity and attachment-count parity too. (developers.freshdesk.com)

Attachment URL expiry

Freshdesk attachment URLs returned by the API are time-limited. Community reports indicate attachment download URLs can expire in as little as 5 minutes. Your migration script must download each attachment immediately after fetching the conversation — not queue them for later batch download.

Alternative export methods

Beyond the paginated API, Freshdesk offers two other extraction paths:

• Contact/company export jobs return downloadable CSVs. These are async — only one export job can run at a time per account, and download URLs expire after 15 days. Useful for flat bulk pulls of identity data.
• Account export jobs produce a broader JSON snapshot that can include tickets, archived tickets, contacts, companies, groups, canned responses, surveys, and more. Use this when you need archived tickets or a configuration snapshot alongside the live API extraction.

(developers.freshdesk.com)

Zendesk Import Limits and Handling 429 Errors

The Zendesk side has its own rate constraints. Understanding these before you start writing import logic will save you days of debugging.

Rate limits by plan

The High Volume API add-on raises the limit to 2,500 requests/min on Growth plans and above (minimum 10 agent seats required). If you are running a large migration (100k+ tickets), purchasing this add-on for the migration window is often worth the cost. (developer.zendesk.com)

Endpoint-specific limits

Some Zendesk endpoints have their own rate limits that override the account-wide number:

• Incremental Exports: 10 requests/min (30 with High Volume add-on)
• Update Ticket: 30 updates per 10 minutes per user per ticket
• Bulk User Import: up to 100 users per request
• Bulk Organization Create: up to 100 organizations per request via create_many
• Ticket Bulk Import: up to 100 tickets per request via /api/v2/imports/tickets/create_many
• Queued background jobs: maximum 30 concurrent jobs

The Ticket Import API

Zendesk's Ticket Import API (POST /api/v2/imports/tickets) is purpose-built for migrations. Unlike the standard Tickets API, it lets you:

• Set historical timestamps: created_at, updated_at, solved_at
• Set created_at on individual comments to preserve conversation chronology
• Import tickets directly into the archive using archive_immediately=true (recommended for 750,000+ historical tickets)
• Suppress trigger execution on imported tickets
• Suppress notification emails to CC'd users

(developer.zendesk.com)

// Zendesk Ticket Import payload example
{
  "ticket": {
    "assignee_id": 12345678,
    "requester_id": 87654321,
    "subject": "Historical Freshdesk Ticket",
    "tags": ["migrated_from_freshdesk"],
    "comments": [
      {
        "author_id": 87654321,
        "html_body": "<p>This is the original customer request.</p>",
        "created_at": "2023-10-12T08:22:11Z",
        "public": true
      }
    ],
    "created_at": "2023-10-12T08:22:11Z"
  }
}

Attachment workflow

Attachments are not embedded in the ticket import payload as raw blobs. Each attachment requires:

1. A GET request to download from Freshdesk (with time-limited URLs)
2. A POST request to upload to Zendesk (/api/v2/uploads) to get an upload token
3. The returned upload token included in the comment payload

Upload tokens are time-limited — they expire at the time specified in the expires_at field. A ticket can contain at most 5,000 comments total. If you are migrating a Freshdesk ticket with thousands of updates, check comment counts before import rather than discovering the limit mid-job. (developer.zendesk.com)

For a 100,000-ticket migration where the average ticket has 2 attachments, that is 200,000 additional round-trips — on top of the ticket and conversation requests.

By default, Zendesk attachment URLs are tokenized but still accessible to anyone who has the URL. Teams with sensitive data should review private attachment settings before go-live.

Retry logic

When you hit the rate limit, Zendesk returns a 429 Too Many Requests response with a Retry-After header specifying the number of seconds to wait. Do not hard-code a fixed sleep interval — the Retry-After value tells you exactly how long the lockout lasts.

import requests
import time
 
def import_ticket(url, payload, auth, max_retries=5):
    for attempt in range(max_retries):
        response = requests.post(url, json=payload, auth=auth)
        if response.status_code == 429:
            wait = int(response.headers.get("Retry-After", 60))
            time.sleep(wait)
            continue
        response.raise_for_status()
        return response.json()
    raise Exception("Max retries exceeded")

Separate your exporter and importer queues. Freshdesk limits and Zendesk limits are independent, and a single shared worker pool makes it harder to identify which side is actually bottlenecking.

Freshdesk to Zendesk Data Mapping: Complete Field Reference

The tables below map Freshdesk objects and fields to their Zendesk equivalents. This is the mapping we use on every Freshdesk-to-Zendesk engagement at ClonePartner, refined over dozens of migrations.

Object-level mapping

Ticket field mapping

The rows to watch most closely are other_emails, view_all_tickets, product_id, and any custom dropdown field with platform-specific option values. Freshdesk supports multiple contact emails, while Zendesk handles multiple user identities through separate identity logic. (developers.freshdesk.com)

Status mapping table

What Breaks: Inline Images, Attachments, and Custom Fields

This is where most migrations silently lose data. The ticket count matches, but the content inside does not.

Inline images

Freshdesk stores inline images (screenshots pasted into ticket replies) as embedded references within the HTML body of a conversation. When you extract that HTML via the API, the <img> tags point to Freshdesk-hosted URLs.

If you import that HTML directly into Zendesk, the images may render initially — until Freshdesk rotates or expires those URLs. Then every historical ticket shows broken image placeholders.

The correct approach: download every inline image during export, re-upload it to Zendesk via the Uploads API, get the new Zendesk URL, and rewrite the <img src> in the HTML body before importing the comment. This is tedious, API-intensive, and the step that most automated tools skip.

Zendesk treats inline images distinctly from regular attachments — the comment listing API has a dedicated include_inline_images flag. Attachment preservation and inline-image preservation are not the same test. Run a sample migration with tickets that contain pasted screenshots inside the conversation body, not just files attached at the bottom of the thread. (developer.zendesk.com)

Attachment size limits and transfer cost

Freshdesk allows attachments up to 20 MB per conversation on paid plans (15 MB on trial/Sprout). Zendesk's API allows attachment uploads up to 50 MB per file, so the size ceiling is not the problem on the Zendesk side.

The problem is the transfer pipeline. Each attachment requires a download from Freshdesk, an upload to Zendesk, and the token attached to the comment — three API calls per file, consuming rate-limit budget on both sides. Many automated SaaS migration tools silently skip attachments over 15–20 MB to save bandwidth and processing time. If your team relies on log files, large PDFs, or video recordings, verify the payload limits of your migration method before committing.

Custom fields

Freshdesk custom fields use a naming convention (cf_fieldname) while Zendesk custom fields are referenced by numeric ID. Before import:

1. Create every custom field in Zendesk manually or via the Ticket Fields API
2. Record the Zendesk field ID for each
3. Build a lookup map: Freshdesk cf_* name → Zendesk field ID
4. Transform every ticket's custom field values during import

Dropdown fields need special attention. Freshdesk stores the display value; Zendesk stores a tag-formatted value. If your Freshdesk dropdown has "Hardware Issue" as an option, Zendesk needs hardware_issue. Miss this transformation and the import silently drops the value.

Comment body formatting

Freshdesk conversations expose HTML bodies. Zendesk imported comments accept value, body, or html_body. If you post plain body, Zendesk collapses repeated spaces and newlines. If the original Freshdesk thread used rich HTML or pasted troubleshooting steps, flattening to plain text changes what agents see. Always use html_body when the source conversation contains formatting. (developers.freshdesk.com)

What else gets lost

Beyond attachments and fields, watch for these commonly dropped items:

• Satisfaction ratings — Freshdesk CSAT data does not map to Zendesk satisfaction ratings automatically. You can store ratings as tags or custom field values.
• Time tracking entries — Freshdesk's time entries are separate API objects. Zendesk tracks time differently. Manual mapping required.
• Forward conversations — No native Zendesk equivalent. Must be appended as private notes with context preserved.
• Automations, macros, and workflows — These do not transfer via API. They must be rebuilt in Zendesk from scratch. See Your Helpdesk Migration's Secret Saboteur: Automations, Macros, and Workflows.

Migration Methods: Native CSV vs. SaaS Tools vs. Engineer-Led

There are three real options. Each has hard trade-offs.

Method 1: Zendesk CSV Import

Zendesk allows bulk importing users and organizations via CSV through the admin UI. CSV files cannot exceed 1 GB, and Zendesk recommends up to 500,000 rows. You can also create tickets via CSV, but with severe limitations.

What it cannot do:

• No conversation history — CSV import creates tickets with a single description, not multi-comment threads
• No attachments
• No timestamp preservation (tickets get current timestamps)
• No custom field mapping beyond basic text fields

Verdict: Useful for importing a user list or a small set of tickets where history does not matter. Not a viable path for a full historical migration. If you try to force historical comments and attachments through a spreadsheet-shaped process, you will end up rebuilding an API pipeline anyway. (support.zendesk.com)

Method 2: SaaS Migration Tools

Self-service tools (like Help Desk Migration) provide a web-based wizard that connects to both platforms and transfers data automatically.

Strengths:

• Low setup effort — connect API keys, map fields, run
• Handles basic ticket + conversation + user migration
• Pricing based on ticket volume

Limitations:

• Inline images are frequently stripped or broken — most tools import the HTML body but do not re-host embedded images
• Large attachments (over 15–20 MB) may be skipped silently
• Custom field mapping is limited to what the tool's UI supports
• Rate limit handling is opaque — you cannot control retry logic or concurrency
• Forward conversations and side notes may be dropped or merged incorrectly
• No ability to handle edge cases (suspended users, empty comment bodies, custom status mapping)

These tools are usually best when your mapping stays close to the default. Once you start hitting edge cases, you are at the mercy of the vendor's support team rather than your own code.

Verdict: Reasonable for small-to-mid migrations (under 50,000 tickets) where you can accept some data loss in edge cases and have time to QA manually.

Method 3: Engineer-Led Custom Migration

A dedicated engineering team writes custom scripts that handle the full export → transform → import pipeline.

Strengths:

• Full control over every field mapping, transformation, and edge case
• Inline images re-hosted and rewritten in HTML bodies
• Attachment pipeline handles rate limits and retry logic on both sides
• Custom status, custom field, and tag normalization built into the script
• Can run incremental syncs to minimize cutover downtime

Limitations:

• Requires significant engineering time (typically 2–6 weeks for DIY)
• Must build and maintain retry logic, error handling, logging, and validation
• API rate limits still apply — script must be tuned for your specific plan tiers

Be honest about what "full control" means if you go DIY. It means owning Freshdesk windowing, conversation fan-out, upload-token expiration, 429 handling on both sides, idempotency, audit logs, and rollback plans. If your team can do that well, DIY works. If not, DIY often becomes delayed outsourcing after the hard bugs surface.

Verdict: The only reliable method for migrations over 50,000 tickets, migrations with heavy attachment loads, or migrations where losing inline images or conversation context is not acceptable.

The ClonePartner Approach: Zero Downtime, Full Fidelity

We have run this exact migration — Freshdesk to Zendesk — many times. Here is how we approach it differently from the options above.

Custom export scripts with built-in rate management. Our scripts read the X-RateLimit-Remaining header on every Freshdesk API response and throttle automatically. We never hit 429 errors in production — we stay just under the ceiling, which means faster total throughput than tools that blast requests and then wait out lockout periods.

Inline image re-hosting. Every <img> tag in every conversation body is parsed, the image is downloaded from Freshdesk, uploaded to Zendesk, and the HTML is rewritten with the new Zendesk URL — before the comment is imported. This is the step most tools skip, and it is the single biggest source of "broken ticket" reports post-migration.

Incremental delta sync. We run the initial bulk migration while your support team continues working in Freshdesk. On cutover day, we run a delta sync that picks up only the tickets created or updated since the last run. The delta window is typically 1–4 hours of data instead of the entire history. For a detailed explanation of how this works, see Zero-Downtime Helpdesk Migration: How to Keep Support Running During the Move.

Suspended user handling. Zendesk's import API rejects tickets where the requester is a suspended or deleted user. We identify these during the pre-migration audit and resolve them before the import starts — not after 10,000 tickets have already failed.

Validation and reconciliation. After import, we run automated reconciliation: ticket count parity, conversation count per ticket, attachment count per conversation, and a sample-based HTML diff on ticket bodies. If the numbers do not match, we investigate before signoff.

Step-by-Step Migration Sequence

Whether you run this yourself or bring in a partner, the execution order matters. Importing in the wrong sequence creates orphaned records and broken references.

1. Audit and map your Freshdesk data

Export a sample of 100–500 tickets with conversations and attachments. Identify all custom fields, custom statuses, tags, and agent/group configurations. Build your field mapping tables. Pay special attention to other_emails, company domains, and view_all_tickets — these affect identity and visibility, not just reporting.

2. Prepare your Zendesk instance

Create all groups, custom fields (with correct field types and dropdown options), and configure organization settings. Disable triggers and automations that would fire on newly created tickets. Disable welcome emails before user import.

3. Import organizations and users

Create organizations from Freshdesk companies first — Zendesk expects organizations to exist before user membership data lands cleanly. Then use the Zendesk Users API to bulk-import contacts as users (up to 100 per request). Establish organization memberships. (support.zendesk.com)

4. Import agents and groups

Ensure every Freshdesk agent has a corresponding Zendesk agent account. Map Freshdesk group IDs to their new Zendesk group IDs. Keep a stable ID map — you will need it for every ticket assignment.

5. Run the ticket import

Use the Ticket Import API. Process tickets in batches of up to 100 via /api/v2/imports/tickets/create_many. Include all comments with original timestamps, re-hosted attachments and inline images, and mapped custom fields. For closed legacy tickets, decide whether archive_immediately belongs in your plan.

6. Run a delta sync

Capture any tickets created or updated in Freshdesk after the bulk import started. Import only this delta set to minimize cutover downtime. The delta window is typically 1–4 hours of data rather than a replay of the entire history.

7. Validate and reconcile

Compare source and target: total tickets, conversations per ticket, attachment counts, user counts, and organization memberships. Spot-check 50–100 tickets manually for inline images, formatting, and author attribution. Verify that attachments over 15 MB transferred correctly and that internal notes retained their private status.

8. Rebuild automations and cut over

Recreate Freshdesk automations, canned responses, and SLA policies as Zendesk triggers, macros, and SLA targets. Data parity does not mean operational parity — this step is a separate workstream. Re-enable triggers post-migration. Update email forwarding, disable the Freshdesk portal, redirect DNS, and brief your support team.

For the complete go-live sequence, see The Go-Live Day Checklist: 15 Things to Do for a Smooth HelpDesk Migration.

When to DIY and When to Get Help

Be honest about your situation:

• Under 5,000 tickets, minimal attachments, no custom fields? A SaaS tool or even CSV import may be fine. Run a test batch and inspect 20 tickets manually.
• 5,000–50,000 tickets with moderate complexity? SaaS tools can work, but plan for a week of QA and manual cleanup on edge cases.
• Over 50,000 tickets, heavy attachments, inline images, custom statuses? You need custom scripts. The question is whether you build them in-house (2–6 weeks of engineering time) or outsource to a team that has done it before.
• Regulated industry (healthcare, finance) with data residency requirements? You need full control over where data transits. Off-the-shelf tools route data through their own servers. Custom scripts or an on-prem migration agent give you that control.

The mistake to avoid is choosing the tool before choosing the fidelity target. Decide first whether you need full historical context, account-level visibility, attachment preservation, and a delta sync. Then choose the method that can actually deliver that outcome.

ClonePartner has run 1,200+ data migrations. We know where the Freshdesk API breaks, where Zendesk's Import API has undocumented quirks, and how to keep your support team running while the data moves underneath them. If your migration is complex enough that you are reading this article, it is probably complex enough to warrant a conversation.