Migrating your customer support data from Zendesk to Intercom is a significant undertaking that reshapes how your team interacts with users. While Zendesk and Intercom both serve as powerful communication platforms, they structure data differently.
Moving from a ticket-centric view to a conversation-centric view requires careful planning and a deep understanding of how these two systems speak to one another.
This guide walks you through the migration process based on a logical object mapping strategy.
Define Your Migration Scope
Before you write a single line of code, you must categorize your data into three buckets: API migrations, manual configurations, and archives.
- Migrate via API: The bulk of your historical data will move programmatically. This includes your Organizations (which map to Intercom Companies), End Users (Contacts), Tickets (which Intercom now supports as a dedicated object), and Ticket Fields (Data Attributes).
You will also migrate your Help Center content, including Categories, Sections, and Articles, as well as Tags. - Manual Configuration: Some objects simply do not have a direct write-path via the API or are efficient enough to handle by hand. Agents fall into this category.
While you can list admins via the API, you generally cannot create them programmatically with permissions intact. Similarly, Groups in Zendesk map to Teams in Intercom, but these are best created manually to ensure the routing logic is sound.
User Segments also require manual reconstruction because the logic defining a segment in Zendesk rarely translates perfectly to the filtering logic in Intercom. - Archive: You should decide if you truly need every ticket from ten years ago. Suspended Tickets and Deleted Tickets usually offer little value in a new system and often clutter your fresh database. It is often wiser to leave these behind or export them to a CSV for cold storage.
Prepare Intercom for Data Import
You cannot move the furniture in until you have built the rooms. You must configure the destination environment first to ensure the data lands correctly.
Start by manually creating your Agents (Admins) in Intercom. This is a critical first step because you will need their new Intercom IDs to map ticket assignments later. If you skip this, your historical tickets will be unassigned or assigned to the generic API token holder.
Next, recreate your Groups by setting up Teams in Intercom. Just like with agents, you want to have these IDs ready so you can route tickets to the correct department during the import.
Finally, you must recreate your schema. Zendesk relies heavily on Ticket Fields to store custom data. In Intercom, these map to Data Attributes or Ticket Type Attributes.
You must create these attributes in Intercom before you attempt to import tickets, or the custom data will have nowhere to go.
Migrate Objects
Once your environment is prepped, you can begin the data transfer. You must follow a specific logical order to maintain the relationships between your data.
- Organizations to Companies: Start by migrating Zendesk Organizations to Intercom Companies. Zendesk organizations group users together, often sharing tickets and comments.
Intercom Companies function similarly. By moving these first, you ensure that when you migrate users in the next step, you can immediately associate them with the correct corporate entity. - End Users to Contacts: Next, migrate your End Users to Intercom Contacts. In Zendesk, users have roles like "end-user" or "agent". In Intercom, these become Contacts (leads or users).
During this step, you will map the Zendesk organization_id to the Intercom Company you created in step one. You should also map any custom User Fields from Zendesk to custom attributes in Intercom to preserve profile data. - Help Center Content: Now you can move your knowledge base. Zendesk structures content into Categories and Sections. Intercom uses Collections to organize content. You will recreate this hierarchy by making Collections in Intercom and then migrating your Articles. Be careful to map the HTML body correctly so your formatting is preserved.
- Tickets: With your users and structure in place, you can migrate the Tickets themselves. Zendesk tickets are the core record of support. Intercom now supports a Ticket object that aligns well with this model.
When you create the ticket in Intercom, you will map the requester_id from Zendesk to the contact_id in Intercom, and the assignee_id to the Admin ID you manually created earlier. - Ticket Comments and Attachments: This is the most complex part of the migration. Zendesk treats Ticket Comments as a stream of updates.
To migrate this history, you generally have to loop through the comments and "reply" to the ticket in Intercom to build the history.
For Attachments, you face a workaround. Zendesk attachments are hosted files. You cannot simply pass the internal Zendesk URL to Intercom.
You must download the file from Zendesk and then upload it to Intercom or a public host, subsequently linking it in the conversation. Intercom allows creating attachments for side conversations and tickets via multipart form data, which you can use to upload the files. - Tags: Finally, apply your Tags. Zendesk uses tags extensively for workflow and reporting. You can apply these tags to your new Contacts and Tickets in Intercom to ensure your historical categorization remains intact.
Post Migration Configuration
After the data is moved, you have some manual cleanup to do.
User Segments defined who could see what content in Zendesk. You need to rebuild these in Intercom manually. You will likely use the Data Attributes you imported to define these audiences (e.g., "VIP Customers" segment based on a "Plan Type" attribute).
You also need to recreate your business logic. Zendesk Triggers and Automations do not migrate via API. You must manually build the corresponding Workflows and Rules in Intercom to handle new incoming conversations.
Insider Secrets
The Author Trap: When you use the API to create comments or tickets, Intercom (and Zendesk) will default the "author" to the owner of the API token.
To make the history look real, you must explicitly map the author_id or create the comment "on behalf of" the original user. If you miss this, your entire support history will look like it was written by one robot.
Rate Limits and Retry: Zendesk and Intercom both have strict rate limits. Zendesk returns a specific header telling you exactly how many seconds to wait before trying again.
If your script does not respect this header, you will get blocked, and your migration will fail silently or have gaps.
HTML Sanitization: Zendesk comments support HTML, but they sanitize it. When you move this content to Intercom, stripping the HTML down to the basics is often safer than trying to preserve complex formatting that might break the Intercom UI.
Idempotency Keys: Scripts crash. If your migration script creates a ticket and then crashes, you don't want to create a duplicate ticket when you restart the script.
Zendesk supports idempotency keys, which allow you to retry a request safely without creating duplicates. Use unique IDs from your source data as your idempotency keys.
Summary
Migrating from Zendesk to Intercom is a linear process of mapping containers (Organizations/Companies), then people (Users/Contacts), and finally content (Tickets and Articles). While objects like Agents and Groups require manual setup, the API allows for a rich transfer of history. Pay close attention to author attribution and rate limits, and your new Intercom instance will feel like home from day one.
At ClonePartner, we’ve completed many Zendesk to Intercom migrations. Each project is handled by a dedicated engineer who customizes the data mapping to match your setup. If you want to avoid the technical complexity, ClonePartner can manage the entire migration for you, from planning and field mapping to validation and go live.