The Zendesk migration guide
Why teams migrate to Zendesk
The four shapes a Zendesk migration takes, and what makes the platform easier — or harder — than the category average.
Zendesk, Inc. was founded in Copenhagen, Denmark in 2007 and is headquartered in San Francisco, California. The company went public in 2014 and was taken private in November 2022 by an investor group led by Hellman & Friedman and Permira for roughly $10.2 billion1. The product is now sold primarily as the Zendesk Suite, which bundles Support, Guide, Chat, Talk and Explore under a single subscription.
The typical Zendesk customer is a B2C or B2B support organisation — anywhere from 5 to 5,000 agents — that runs multi-channel inbound volume across email, web widget, mobile, voice, chat and social. Compared with Freshdesk and Help Scout, Zendesk positions itself on workflow depth; compared with ServiceNow CSM and Salesforce Service Cloud, it positions on faster time-to-value and a flatter admin function.
The shapes of migration that actually land on Zendesk tend to fall into four patterns. First, consolidation projects: a company replacing a stack of Intercom plus Help Scout plus a homegrown ticket tool with Zendesk Suite. Second, exits from competing helpdesks — Freshdesk, Front, Kustomer, Gladly — usually triggered by feature gaps in routing, SLAs or Explore-style reporting.
Third, legacy replacements — Jira Service Management, Spiceworks, on-prem ServiceNow, or shared mailboxes — where the source has no real ticket model and the project is really a re-architecture. Fourth, M&A integration, where an acquired business runs on a different helpdesk and the parent standardises on Zendesk. Each shape has a different difficulty profile: a Freshdesk migration has clean ticket-and-user parity but messy tag spillover; a shared-mailbox migration has no schema at all.
What makes migrating to Zendesk easier than the category average is the dedicated Ticket Import path that preserves historical created_at, updated_at and solved_at timestamps, does not fire triggers or automations during import, and accepts batches of up to 100 tickets at a time23.
What makes it harder than the average is that triggers, automations, macros, SLA policies, views and Guide content do not import — they are rebuilt from the source's documentation in Zendesk's own admin UI. Multi-brand customers also discover late that Sandbox availability is plan-gated (Suite Professional and above), which forces some teams to dry-run on production27.
Ticket-field tagging, drop-down tag collisions and the 50-tag-per-ticket cap also reward teams that design the tag taxonomy before the first row is imported.
Teams that scope the trigger, macro and Guide rebuild work up front finish on time; teams that assume parity do not.
The Zendesk data model you need to map into
Tickets, users, organizations, brands, custom objects, and the external-ID keys you'll wire on every field — the destination schema decoded.
Zendesk Support is built around a small set of standard objects, each with default and custom fields, and lookup relationships that connect them. The Suite layer adds Guide articles, Talk calls, Chat conversations and Sunshine custom objects on top of the same shared schema used by Support.
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 Zendesk Suite migration.
| Object | What it stores | Required | Tier |
|---|---|---|---|
| Tickets | Support requests across all channels | Requester, subject, comment body, status | All tiers |
| Users (End users + Agents) | Customers, agents, admins, light agents | Name + email (or external_id) | All tiers |
| Organizations | Customer accounts; group end users | Name (unique within instance) | All tiers |
| Groups | Agent assignment groups for routing | Name | All tiers |
| Brands | Multi-brand routing + branded help centers | Name, subdomain | Suite Growth+ (Multi-brand) |
| Ticket Forms | Templates that scope ticket fields per workflow | Name, ordered field list | Suite Growth+ (multiple forms) |
| Custom Objects (Sunshine) | Customer-defined record types | Object key, name field; plan-scaled fields | Suite Team+ (counts scale by tier) |
| Guide articles, sections, categories | Help Center knowledge base content | Title, body, section, locale | All Suites (Guide) |
| Macros, Triggers, Automations, SLAs, Views | Business rules and routing logic | Rebuilt manually, not imported | All tiers (Automations: Growth+) |
Users use email as the de facto unique identifier, but the most reliable upsert key is external_id — a free-form string you populate from the source system's primary key. Organizations also expose external_id and an organization name that is unique across the instance4.
Tickets are typically matched on the Zendesk-assigned ID after creation, but during a migration the pattern is to stamp the source ticket ID into a custom ticket field (often called legacy_ticket_id) so re-runs and reconciliation are deterministic. Custom objects expose a first-class external_id field designed for exactly this purpose6.
The Data importer upserts on the identifier you nominate: if a matching record exists, it updates; if not, it creates7. The Ticket Import path does not upsert — it always creates — so any re-run requires you to delete failed rows or reconcile by legacy_ticket_id before retrying. Custom field types determine validation; the catalogue below covers what you can model and the limits you plan around.
| Field type | Limit | Notes |
|---|---|---|
| Text / Textarea | Free-form string | Standard short and long text |
| Date | YYYY-MM-DD | Sell importer also accepts DD/MM/YYYY if account timezone matches8 |
| Integer / Decimal | Standard numeric range | Decimal stores numbers with decimal point |
| Checkbox | Boolean + optional tag | Optional tag writes a tag to the ticket on true |
| Dropdown (tagger) / Multi-select | Tag value per option, 255-char regex caps | Each option writes its tag to the ticket; tags must be unique across all custom fields9 |
| Regexp | ≤255-char pattern | Ruby regex syntax; validates string input9 |
| Lookup relationship | Targets: ticket, user, organization, custom_object, brand, article | Custom field type lookup; mapped via target object ID10 |
| Ticket fields per account | ≤400 fields per account, or 400 per form | Above this, performance degrades11 |
| Custom objects per plan | 3 / 5 / 30 / 30 / 50 / 50 | Team / Growth / Pro / Support Enterprise / Suite Enterprise / Enterprise Plus12 |
Relationships in Zendesk are modelled three ways. Tags are the loose-coupling primitive — every ticket can carry up to roughly 50 tags. Lookup relationship fields are first-class typed references between tickets, users, organizations and custom objects, including dynamic filter definitions10. Custom-object parent-child relationships were added in 2024 alongside roll-up summary fields, and many-to-many is modelled via a junction custom object13.
Legacy Sunshine custom objects will be removed in June 202614. Plan to migrate object types, schemas, relationship types and records into the new custom-objects framework before the deprecation deadline, not as part of the cutover itself.
Pre-migration prep — the work before you touch Zendesk
What must be true on the source, the destination, and across the team before the first row hits the Data importer.
The single best predictor of a clean Zendesk migration is how much work you do on the source side before the first import is queued. Help Desk Migration's own playbook notes that roughly 60 percent of total migration effort sits in the pre-transfer phase, and the fix is almost always pre-processing rather than post-cleanup.
Around 60 percent of total migration effort sits before any data moves — the fix is pre-processing, not post-cleanup.
Treat the source export as raw material that needs to be shaped to Zendesk's expected formats — CSV files saved as UTF-8 (not ISO-8859), dates rewritten to match account timezone, email lowercased, tags normalised with dashes instead of spaces, and source ticket IDs preserved in a legacy_ticket_id custom field16.
Source-side prep
- Audit the ticket estate. Count tickets per channel, per status and per year. Decide what window you actually need in Zendesk — most teams import 2 to 3 years of solved/closed and only the open backlog beyond that.
- Dedup users by email. Two source rows with
[email protected]and[email protected]will collapse into one Zendesk user on import; if you want them separated, deconflict the email before export. - Convert tags so they contain no spaces — Zendesk replaces spaces with dashes silently and you lose the ability to filter on the original string.
- Stamp
legacy_ticket_idandlegacy_user_idcustom fields on every record in the source export so re-runs are deterministic and conversation threads can be linked back to the source if a discrepancy appears post-cutover. - Decide what is in scope for ticket comments. Public comments and internal notes are both imported via the ticket
comments[]array3; deciding to drop internal notes is a one-time decision that cannot be reversed without a re-import.
Destination-side prep
- Request a Sandbox if you are on Suite Professional or above — a single Sandbox is allowed at a time, and the typical procedure is to delete the existing one and create a new one based on current production settings18.
- Enable data imports — they are not enabled by default. The account owner or an admin must contact Zendesk Customer Support to turn on the Data importer and bulk export access7.
- Disable required conditions on ticket forms during the import window. Required ticket fields will reject historical rows where the source did not capture that value; flip the requirement off in Admin Center → Objects and rules → Tickets → Forms → Conditions before importing, and re-enable after.
- Provision agents and groups first, ideally through SSO with Okta or Microsoft Entra ID, and create the role assignments before importing — ticket-assignment fails silently if the referenced assignee does not exist in Zendesk.
- Pre-create every ticket field, ticket form, brand, organization custom field and user custom field with the correct type and tag value. Dropdown tag values must be unique across all custom fields on the account9.
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 channel that touches the inbox. Train agents on the Zendesk macro library, the views they will work from, and the new SLA policies before go-live. A single-brand migration under 10,000 tickets runs one to two business days; a multi-brand, Talk + Chat + Guide consolidation runs two to six weeks.
Import mechanisms: Data importer, Ticket Import, and ETL
Multiple paths in, each with different limits and shapes. Picking the wrong one is how mid-migrations stall at scale.
Zendesk exposes several load paths and the right one depends on dataset size, object mix, and whether you need to re-run idempotently. The native Data importer covers users, organizations and custom-object records up to mid-volume. The Ticket Import path is the sanctioned route for historical tickets at scale. Third-party migration tools sit on top of both and add staging, transformation and reconciliation layers.
Data importer (UI)
The native importer lives at Admin Center → Objects and rules → Tools → Data importer and replaces the legacy Bulk actions page19. It accepts a CSV file (UTF-8 only16) and supports three record types: users, organizations and custom-object records. It does not import tickets — that path is Ticket Import. The legacy bulk-actions page caps at 2,000 rows per file20; the new Data importer benefits from chunking at large volumes.
Bulk export of users via CSV is throttled to 100,000 results per hour per user21. The right call: Data importer for any one-shot users / organizations / custom-object load under a few hundred thousand records where you want a visual mapping review before commit.
Ticket Import
The Ticket Import path is dedicated to moving historical tickets and is documented separately from standard ticket creation3. The bulk form processes up to 100 tickets per batch322.
Unlike standard ticket creation, the import path preserves historical created_at, updated_at and solved_at timestamps, supports an archive_immediately parameter for closed tickets, does not trigger business rules (triggers, automations, notifications) on import, and lets you set custom comment timestamps per element of the comments[] array3. The requester user must already exist in Zendesk — pre-load users via the Data importer first.
Bulk operations that take longer than a single request queue background jobs. The platform ceiling is 30 queued-or-running jobs at once23. Exceeding it returns TooManyJobs; respect the remaining and reset values and back off. Plan-tier throttles sit on top — Team plans run lower request caps than Enterprise23. Choose the programmatic path when ticket volume is over a few thousand.
Third-party migration and ETL tools
Specialist Zendesk-targeted migration tools handle file generation, type coercion, attachment fetching and conversation-thread reconstruction before the result is fed to Zendesk. ETL platforms like Fivetran, Airbyte, Stitch and Talend Data Integration are commonly used for the reverse direction — staging Zendesk data into a warehouse — but on the inbound side they are typically used to land source data into a warehouse, transform in SQL, then push into Zendesk.
Mapping your data into Zendesk
The longest section — because field mapping is where almost every helpdesk 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 reports work on day two, whether SLA breaches fire correctly on day five, and whether your agents trust the ticket history on day thirty.
Work object by object, top to bottom of the import order: Organizations first (so users can associate), then Users, then Tickets (with comments inline), then Guide content, then Custom Objects.
Users and organizations
| Source | Destination | Note |
|---|---|---|
| email (primary identity) | Lowercased on import; case-only duplicates collapse | |
| source primary key | external_id (User / Organization) | First-class upsert key — populate on every row |
| name / full_name | name | Single string; concatenate first + last if needed |
| phone | phone | Normalise to E.164 before import |
| role | role (end-user / agent / admin) | Agents must hold a paid seat; light agents are read-only on Pro+ |
| account / company | organization_id via Organization name or external_id | Pre-load organizations first; user import resolves the FK |
| custom attributes | user_fields.{key} / organization_fields.{key} | Field key must pre-exist; use snake_case lower |
Tickets — history, comments and conversation threads
Tickets are the heart of the migration. Every public comment and internal note from the source needs to land in Zendesk's comments[] array in the right chronological order with the right authorship and the right public/private flag. The Ticket Import path accepts a fully composed ticket plus comments in a single payload3, which means you do not have to make a second pass to backfill the conversation thread.
| Source | Destination | Note |
|---|---|---|
| subject / title | subject | Required |
| ticket_id | Custom ticket field legacy_ticket_id (regex or text) | Zendesk assigns its own ID; keep the source ID for reconciliation |
| requester_email | requester_id via user lookup | Requester must exist in Zendesk before the import |
| status | status | Map to new / open / pending / hold / solved / closed |
| priority | priority | low / normal / high / urgent |
| channel / source | via.channel + custom field if richer mapping needed | Native channels: email, web, mobile, voice, chat — keep original in a tag if consolidating |
| created_at, updated_at, solved_at | created_at, updated_at, solved_at | Preserved by Ticket Import; pre-1970 dates rounded to 19703 |
| ticket form (if multi-product) | ticket_form_id | Form must pre-exist; tag values from form-scoped dropdowns must match |
| comments[].body + author + is_public | comments[] with public, author_id, created_at | Internal note = public: false; preserve per-comment timestamp3 |
| tags | tags[] | Replace spaces with dashes; ~50-tag soft cap per ticket |
| brand (if multi-brand) | brand_id | Brand must pre-exist; routing follows brand on Growth+ |
| CCs / followers | collaborator_ids / follower_ids | Adding on create mirrors notification history |
| attachments | comment_attachments via the Uploads path | Upload binary first → receive token → attach to comment |
Side Conversations — Zendesk's way to email or message out from a ticket without polluting the main thread — are an under-imported artefact. Most migration tooling collapses them into a private note at the bottom of the ticket because there is no public way to recreate them with their original participant graph intact. Decide whether you accept that trade-off or whether the lost context warrants a manual re-create for high-value historical tickets.
Knowledge base (Guide) — categories, sections, articles, translations
Help Center content imports as categories → sections → articles28. Categories and sections are containers; articles carry the body HTML, locale, draft flag and labels. Translations are imported per-locale through the same path — the UI does not bulk-import translated content, so multi-locale knowledge bases require scripted work28.
Inline image URLs in article bodies need to be rewritten — pointing at the source platform's CDN means the images break the moment that account is cancelled. The pattern is to download every referenced image, re-upload to the Articles Attachments path, capture the new URL, and rewrite the body HTML before insert. Article comments are kept in a separate object and are imported only if your historical knowledge base depended on community discussion.
Macros, Triggers, Automations and SLAs — the rebuild list
Macros (manual actions an agent applies to a ticket), Triggers (event-driven business rules that fire on ticket create or update), Automations (time-based rules that run hourly), SLA policies (response and resolution targets bound to ticket conditions), and Views (saved filters that agents work from) do not import. They are rebuilt from the source platform's documentation in Zendesk's own admin UI.
Plan for this as a parallel workstream, not a post-import task — the rebuild is the work, not the data move. Export the source's automation rules as a spreadsheet with three columns: trigger condition, what it does, who owns it. Filter out anything inactive in the last 90 days. Anything left over is the rebuild backlog. Business hours and schedules are also rebuilt: SLAs reference schedules, so the schedule definitions need to exist before SLA policies are created.
CSAT history and survey responses
Zendesk's CSAT survey writes a satisfaction_rating value (good / bad / offered / unoffered) and an optional comment to the ticket itself. Historical CSAT from a source platform cannot be backfilled into the native satisfaction_rating field on import — the recommended pattern is to land legacy survey scores in a custom ticket field (legacy_csat_score) and a legacy survey comment field, then rewrite historical-period CSAT reports to point at those fields rather than the native one.
Multi-channel inbox setup — Email, Web Widget, Mobile, Voice, Chat, Messaging
The migration moves historical tickets; the live channels still have to be cut over separately. Email is the simplest — point the source mailbox MX or a forwarding rule at {your-subdomain}.zendesk.com. The Web Widget and Mobile clients need to be re-embedded with the new account credentials. Zendesk Talk numbers are ported via a separate carrier porting process that runs in parallel and takes one to four weeks.
Chat (legacy) is being superseded by Messaging (Sunshine Conversations), and many migrations consolidate from third-party chat to Messaging at the same time as the helpdesk move. Social channels (Facebook, X, WhatsApp via Sunshine Conversations) reconnect through the Channel Framework. Brand-specific routing — assigning the right group, ticket form and SLA policy to each brand — is configured in Admin Center → Account → Brand management once Brands are pre-created.
Files, attachments and inline images
Email and web-form attachments cap at 50 MB per inbound file and outbound email attachments cap at around 7 MB total per email29. Attachments are uploaded first, returning a token that you attach to a ticket comment in the same import call. For Guide articles, the per-attachment cap is 20 MB per file or image and community post images are capped at 2 MB30.
Plan for storage tier consumption — Zendesk meters file storage by GB per agent, and the storage dashboard in Admin Center → Account → Usage → Storage refreshes every 24 hours31. For large attachment estates (multi-TB), the pattern most teams adopt is: keep originals in S3 or Azure Blob, store a deep link in a custom ticket field, and only inline-upload the most recent or most-referenced subset to keep storage costs predictable.
Audit trail, ownership and original timestamps
The Ticket Import path is the only route that preserves created_at, updated_at and solved_at on historical tickets — standard ticket creation stamps them to import time. For users and organizations, there is no equivalent override: the Data importer always sets created_at to the moment the row is processed. If you need the original user-created date for reporting, capture it in a legacy_created_at user field.
Ownership during import works through the submitter_id and assignee_id fields on the ticket, both of which must resolve to existing Zendesk user IDs at the moment of import. Rows whose assignee cannot be resolved are imported unassigned, which silently breaks downstream group-based views and reports. The Ticket Audits view exposes the full event timeline post-import32 — useful for reconciliation but not for backfilling: import-generated audits are stamped to import time, not to the source events.
The pitfalls that derail Zendesk migrations
Specific failure modes — ranked by impact, each tied to the exact Zendesk 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 Supportbench playbook recommends a three-stage validation: a small-scale test load with stakeholder spot-checks, the full load with real-time monitoring of ticket counts and conversation integrity, and a post-migration data-quality audit that runs for 30 days. The most reliable signal is having team leads verify their own ticket queues — they know what right looks like better than any reconciliation script.
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, closed-no-comment, out-of-scope years).
- Tickets per status (new / open / pending / hold / solved / closed) vs source — a non-trivial drift usually signals a status-mapping error.
- Tickets per brand and per ticket form vs source — confirms multi-brand routing landed correctly.
- Comments per ticket — sum of public + private comments vs source, sampled across 100 high-traffic tickets to confirm the
comments[]array round-tripped intact. - Attachments per ticket — count + bytes; missing attachments are usually a token-expiry or content-type problem on the upload step.
- Users imported vs source distinct emails — confirms email-case-only collisions did not over-merge.
- Tags distribution — top 50 tags by frequency vs source; tags with spaces should appear with dashes and counts should match.
- Original timestamps — sample 50 historical tickets and confirm
created_atmatches source within 1 second; this is the single most common silent failure on the Ticket Import path.
On top of reconciliation, run a manual spot-check protocol: pick 30 random tickets across statuses, channels and brands and verify each comment, attachment and tag against the source UI. Pick five highest-touch tickets and trace the full conversation graph — every public reply, every internal note, every attachment, every Side Conversation collapse. If a non-trivial discrepancy shows up in three or more of the 30, halt the load, fix the root cause, and re-import the affected rows by legacy_ticket_id.
Zendesk does not offer a native bulk-undo. The Data Recovery Policy is explicit that Zendesk will not restore data the customer deletes36. The supported pattern is: export every object to your own storage before the import starts, stamp every imported ticket with an Import Batch ID custom field, and if catastrophe strikes, bulk-delete by that batch ID and re-import from the cleaned source36.
Cutover sequencing: (1) source helpdesk goes read-only; (2) final delta export captures changes during the test-import window; (3) delta is imported with archive_immediately: true for closed tickets; (4) reconciliation queries run; (5) email MX / forwarding flips to the new Zendesk subdomain; (6) Web Widget and Mobile clients are re-pointed; (7) agents get login with a 48-hour hyper-care window; (8) source decommission is scheduled 30 to 90 days out, never the same day.
Migration partners and tools
Solutions partners, automated migration services, ETL vendors — what each is good for and how to choose.
The Zendesk Solutions Partner Directory tiers Premier, Select and Member partners by certifications, customer count and regional coverage. For a Suite migration specifically, partners with explicit Freshdesk-to-Zendesk, Intercom-to-Zendesk or shared-mailbox-to-Zendesk practices tend to ship cleaner than generalist implementation shops because the failure modes in helpdesk migrations are pattern-matched rather than discovered live.
Alongside certified consultancies, a second category exists: automated migration services that wrap the Ticket Import and Help Center paths in a SaaS UI with field-mapping, demo migrations and delta-sync. These services typically price per-record on a sliding scale, with separate line items for inline-image rebuild, custom-object records, Side Conversations preservation and post-cutover delta runs.
On the ETL and iPaaS side, Fivetran, Airbyte, Stitch, Matillion and Talend Data Integration all have Zendesk 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 tag conventions and resolves owner IDs, and the ongoing-sync layer that takes over once the one-time migration is complete.
Managed-migration cost ranges vary widely. Automated tool quotes start around $800 for under-10,000-ticket transfers, but practitioners report true project cost lands 4×–40× higher once configuration rebuild, inline-image fixes, retry orchestration and custom-object recovery are factored in. Implementation, migration and training services for enterprise Zendesk deployments are quoted in the $5,000–$50,000+ range. Drivers: ticket volume, custom-field complexity, multi-brand count and integration rebuilds.
For teams that want to outsource the migration end-to-end, FlitStack specialises in Zendesk migrations and handles the field mapping, ticket-history and comment preservation, KB article and inline-image rebuild, custom-object record migration, 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 multi-brand setups and Side Conversation preservation 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 Zendesk Solutions Partner, an automated migration service, an iPaaS-first approach, or a specialist migration vendor. [Explore FlitStack →](/contact)




