Zendesk Migration Checklist

Migrating your support operations to Zendesk requires careful planning and execution. The complexity varies dramatically depending on your source platform, data volume, and how much historical context you need to preserve.

This checklist covers the full migration process — from scoping and setup through execution and post-migration validation. It's written for teams migrating from platforms like Freshdesk, Intercom, Help Scout, Salesforce Service Cloud, or any system with exportable ticket data.

Scope the Migration

Start by defining the scope of your migration. This phase will determine what needs to be brought over and what can be left behind.

• Historical Data Range: How far back should you migrate? The answer depends on your compliance requirements and operational needs. Regulated industries (healthcare, finance) may need full history. For most B2B SaaS support teams, 1–3 years covers active customer context without importing noise. Check your retention policies before deciding.

• Identify Users and Agents: Include all active agents and legacy agents whose names appear on historic tickets to ensure proper ownership. In Zendesk, if a ticket's requester doesn't exist at import time, the import can silently fail or assign the ticket to a default user — so agents and end-users must be created before ticket import.

• Select Objects for Migration: Decide which data needs to be migrated, such as:

  • Tickets, conversations, messages
  • Customers, companies, and profiles
  • Tags, custom fields, and ticket metadata
  • Attachments, internal notes, and other files

• Determine What to Skip: Identify irrelevant data such as spam, test tickets, and outdated records.

• Mapping Legacy Data: Document how old statuses, priorities, custom fields, and tags map to Zendesk's ticket and user system. This is where source-platform specifics matter most — Freshdesk's "priority" values don't map 1:1 to Zendesk's, Intercom's conversation model is structurally different from Zendesk's ticket model, and Help Scout's "mailbox" concept needs to be translated into Zendesk's group/brand structure.

Choose Your Migration Method

The right approach depends on your data volume and technical capacity:

CSV imports are simplest but lose attachments and threading. The Zendesk Ticket Import API (POST /api/v2/imports/tickets.json) preserves timestamps, allows backdating, and supports up to 100 tickets per batch request. For exports from the source system, the Incremental Export API (if migrating between Zendesk instances) uses cursor-based pagination and is designed for large datasets.

What Can Be Migrated Via API

Zendesk's API allows for programmatic data transfer. The following critical data types can be migrated:

• Users & Organizations: Migrate customer profiles, their contact details, legacy IDs, and associated organizations. Note: organization domain auto-association can cause users to be linked to the wrong organization if domain fields aren't cleaned before import.
• Tickets & Conversations: Rebuild tickets as conversations, preserving the full message history, internal comments, timestamps, and attachments. Closed tickets cannot be reopened via the standard API — use the Ticket Import API to create them directly in the correct end-state.
• Attachments: Import images, PDFs, and documents and attach them to the correct ticket, retaining filenames and formats. Zendesk rejects certain MIME types and enforces a per-attachment size limit (typically 50 MB on most plans). Validate attachment sizes and types before migration.
• Tags & Custom Fields: Recreate legacy tags and custom fields, ensuring proper alignment with Zendesk's ticketing model. Custom fields must exist in Zendesk before import — the API will silently drop values for fields that don't exist.
• Ticket Metadata: Include important ticket metadata like statuses (open, solved, pending) and priority levels.

Zendesk API Rate Limits

Zendesk enforces rate limits that directly affect migration speed:

• Standard plans: 400 requests per minute
• Professional/Enterprise plans: 700 requests per minute
• Ticket Import API: Subject to the same rate limits, but batch requests (up to 100 tickets per request) help maximize throughput

At 700 requests/minute with 100 tickets per batch, the theoretical maximum is ~70,000 tickets per minute — but real-world throughput is lower due to attachment uploads, error handling, and retry logic. A realistic estimate for migrating 100,000 tickets with attachments via API is 4–8 hours.

What Needs to Be Configured in the Zendesk UI

While the API handles much of the heavy lifting, there are several key elements that need to be manually configured within Zendesk's user interface:

• Mailboxes & Email Channels: Set up your email channels, including support and sales inboxes, and configure routing rules.
• Users & Teams: Invite agents, assign roles (Admin, Agent, Light Agent), and configure team structures manually.
• Workflows & Automations: Create automation rules such as auto-assign based on tags, keywords, or specific triggers. These need to be rebuilt in the UI. Migrated tickets can trigger automations unintentionally — disable all triggers and automations before import, then re-enable after validation.
• Macros & Saved Replies: Pre-configure commonly used macros and canned responses to speed up agent workflows post-migration.
• Help Center Content: While articles can be imported via the API, you will need to manually set up help center sections, SEO settings, and article organization.

Pre-Migration Setup in Zendesk

Before migrating data, it's crucial to set up the target environment to ensure smooth data transfer.

1. Create Your Zendesk Account & Set Up Core Settings:
   • Choose the right Zendesk plan that suits your needs (e.g., support, tickets, reporting).
   • Configure organization settings (company name, timezone, default language).
   • Set up roles and permissions for key stakeholders (admins, lead agents).
   • Generate an API token (Admin > Channels > API) for authentication. API token auth is simpler than OAuth for migrations and sufficient for admin-scoped operations.
2. Configure Teams, Roles, and Permissions:
   • Create all active agents and any legacy agents (for ticket ownership mapping).
   • Assign appropriate roles (Admin, Agent, Light Agent).
   • Set up team structures, ensuring the right permissions for each role.
3. Map Legacy Data to Zendesk Fields:
   • Pre-create custom fields, ticket statuses, and priority levels.
   • Define ticket categories and tags.
   • Set up triggers and automation rules for post-migration workflows — but keep them disabled until migration is validated.
4. Disable Triggers and Notifications:
   • Turn off all email notifications, triggers, and automations before import. Imported tickets will fire triggers if they match conditions, which can send hundreds of thousands of emails to customers.
5. Test with Small Pilot Import:
   • Import a small set of sample data (e.g., 100 contacts and 50 tickets) to verify the accuracy of mappings.
   • Check ticket threading (are replies nested correctly under the parent ticket?), attachment visibility, and data integrity.
   • Verify that legacy IDs (if stored in a custom field) are correctly preserved for cross-referencing.

Migration Execution

Now it's time to run the full migration. Here's how to execute it smoothly:

1. Import Users & Organizations First: Begin by importing your user base, ensuring each contact is properly linked to their respective organization. The ticket import will fail or misattribute if requesters don't exist yet.
2. Migrate Tickets & Conversations: Import tickets as conversations, preserving their threads, attachments, status, timestamps, and participant assignments. Attach tickets to the correct users and organizations. Note: Zendesk reassigns ticket IDs on import — original IDs are not preserved. Store the source system's ticket ID in a custom field if you need cross-referencing.
3. Run Delta Import: After the initial import, capture any new data (e.g., tickets created after the initial export) through a delta import. A "delta import" means re-exporting only records created or modified after the initial export timestamp, then importing just those records. This closes the gap between export and go-live.
4. Switch Email Routing: Change the email forwarding and routing rules so that new tickets are routed into Zendesk, not the old system.
5. Re-enable Triggers and Automations: Only after confirming the import is clean, turn automations and notifications back on.
6. Monitor API Calls and Errors: Track API usage and fix any failed imports or errors as they occur. Common errors include RecordInvalid (missing required fields), TooManyRequests (rate limit exceeded), and Unprocessable Entity (invalid field values or attachment failures).

Post-Migration Validation

Once the data is loaded and agents are actively using Zendesk, perform these checks to ensure everything is functioning correctly.

• Data Verification:

  • Count validation: Compare total ticket counts, user counts, and attachment counts between the source system and Zendesk. Use the Zendesk Search API or the admin dashboard to pull totals. Any discrepancy indicates dropped records.
  • Spot-check records for accuracy. Verify ticket ownership, timestamps, and attachments.
  • Ensure customers and organizations are linked correctly.
  • Verify that non-UTF-8 content (common in legacy systems) hasn't been corrupted or stripped during import.

• Channel & Workflow Testing:

  • Test each channel (email, chat, social) to ensure that new tickets are routed correctly.
  • Verify that workflows, triggers, and SLAs function as expected.

• Agent Readiness:

  • Ensure agents have the correct permissions and roles.
  • Train agents on Zendesk's workflows, including internal comments, macros, and collaboration features.

• Final Cleanup & Cutover:

  • Once everything looks good, make the old system read-only or decommission it entirely.
  • Re-enable any customer-facing notifications and workflows that were paused during migration.

Common Migration Failures and How to Avoid Them