Intercom Migration Checklist

If you are about to migrate your help-desk or support operations into Intercom, having a clear checklist of what to do, what to avoid and what to look out for makes the whole process smoother.

After handling many migrations into Intercom, we can tell you that the teams who prepare the account well, test early, and understand Intercom's data model always have a calm cutover.

This checklist guides you from planning, through pre-migration setup, into the actual import, and finally your post-go-live checks.

What can be migrated via API

Think of Intercom's API as your way to rebuild the backbone of your old helpdesk inside Intercom. You can recreate people, companies, tickets or conversations, and a lot of the context that lives around them.

Here is a quick reference for what falls where:

Category	API-migratable	UI-only configuration	Not migratable
Contacts (users, leads, visitors)	✅ Create, update, bulk import	—	—
Companies	✅ Create, update, link to contacts	—	—
Custom data attributes	✅ Define and populate	—	—
Conversations & messages	✅ Create, import history	—	—
Tickets & ticket types	✅ Create types, states, attributes	—	—
Tags & notes	✅ Create and apply	—	—
Articles & help center content	✅ Via API or Zendesk importer	Collections, ordering, branding, SEO	—
Events	✅ Create and link to contacts	—	—
Workflows, rules, bots (Fin, custom bots)	—	✅ Visual builder only	—
Outbound Series & campaigns	—	✅ UI only	—
Channels & inboxes	—	✅ UI only	—
Teammates, roles, teams	—	✅ UI only (invite, assign)	—
Workspace, region, plan, SSO	—	✅ UI only	—
Macros / saved replies	—	—	❌ No API import path
SLA policy history	—	—	❌ Not transferable
CSAT / satisfaction survey responses	—	—	❌ Historical data not importable
Agent performance metrics	—	—	❌ Not transferable
Workflow automations from source system	—	—	❌ Must be rebuilt manually

People (users, leads, visitors)

Intercom treats people as contacts. These can be users, leads, or visitors, all handled via the Contacts API. You can create and update contacts with identifiers like user_id and email, plus names, phone numbers, social profiles and location data.

You can also import them in bulk from CSV in the UI, which Intercom actually recommends as the first step in historical migration.

In practice, you will:

• Recreate all customers as Intercom contacts
• Preserve their legacy IDs and key traits as custom attributes
• Attach them to the right companies

Companies

If your old system has accounts or organisations, those become companies in Intercom. The API lets you create, list and update companies, then attach them to contacts.

During migration you can:

• Import all companies with their attributes, such as plan, segment, MRR or lifecycle stage
• Link users to companies so Intercom shows the correct account relationship on each profile

Custom attributes and metadata

Intercom's data attributes are where your custom fields live. You can define custom attributes for contacts, companies and conversations via the data attributes API, then populate them when you create or update records.

That means you can migrate:

• Legacy ticket IDs
• Old system tags or statuses
• Segmentation fields and health scores
• Any other metadata that matters to your workflows

Conversations and messages

Conversations are the heart of Intercom. The Conversations API lets you list and retrieve conversations, and the Messages API lets you create user or lead initiated messages and admin messages.

For historical migration you typically:

• Rebuild each legacy ticket as either an Intercom conversation or an Intercom ticket (if you use the Tickets product)
• Import the message history as conversation parts in the correct order, preserving timestamps and authors
• Attach the conversation to the right contact and company

Intercom's own migration guide calls out that you must decide early whether each source record becomes a conversation or a ticket in Intercom.

Conversation vs. ticket — how to decide:

Criteria	Use a Conversation	Use a Ticket
The record is a back-and-forth chat thread	✅	—
You need structured states (submitted → in progress → resolved)	—	✅
The record maps to a specific ticket type or category in your old system	—	✅
You only need to preserve message history for agent reference	✅	—
You plan to report on ticket types, SLAs, or resolution workflows	—	✅
The source system had no formal ticket concept	✅	—

Make this decision per source record type before you start importing — changing it after the fact means re-running the migration.

Tickets and ticket types

If you are using Intercom Tickets, you can also migrate structured tickets, not just conversational history. The Tickets API supports creating tickets, ticket types, ticket states and ticket attributes.

In practice this lets you:

• Create ticket types that map to your old ticket categories
• Define custom ticket attributes for fields like priority, channel, product area
• Import ticket records with links back to their conversations and contacts

Tags, segments and notes

Intercom's API also gives you control over tags, segments and notes.

During migration you can:

• Recreate important tags and apply them to contacts and conversations
• Attach notes to contacts to preserve internal context or migration logs
• Retrieve or apply segments programmatically if you are mirroring complex targeting rules

You may not always recreate every legacy tag or segment, but you can bring over the ones that matter most.

Articles and help center content

For help center content, you have two paths:

• If you are coming from Zendesk, Intercom provides a built in importer from the Articles UI that pulls published Zendesk content directly into Intercom Articles with matching collections.
• If you are coming from other systems, you can use the Articles API and App Store apps to import articles, categories and related records.

Events and activity

If your old system stored events like "ticket viewed", "plan upgraded" or "churned", you can recreate these as events in Intercom via the Events API, linked to contacts. This is optional for a helpdesk-only migration, but very useful if you want Intercom to drive product messaging or Fin behaviour based on past activity.

What still needs to be configured in the Intercom UI

Even with a rich API, a lot of the foundation of an Intercom workspace is still set up by hand. Your migration checklist should make that visible, so your admins know what they own.

Workspace, region, plan and security

The core workspace settings are all UI-driven. You choose your plan, pick your region (US, EU, Australia), define your workspace name, configure authentication and SSO, and set global security settings here.

These choices affect:

• Which API base URL you use
• Where your data is stored
• Which features, such as Tickets or Fin, are available

Channels and inboxes

You connect channels through the Intercom UI. That includes your:

• Support email addresses
• Messenger widget on web and mobile
• WhatsApp, Facebook, Instagram or other social channels

You decide which inbox they feed into, how they are routed and which teammates see them. None of that is created via API.

Teammates, roles and teams

While the API lets you work with teams in some cases, inviting teammates, assigning roles and building your team structure is done in the app. You will:

• Invite teammates by email
• Assign custom roles and permissions
• Decide who can manage settings, billing, articles and automation

Intercom has separate documentation on setting up custom roles and adding your Support team, and these are UI workflows, not API workflows.

Workflows, rules and bots

Intercom's workflows, rules, and bots (including Fin and custom bots) are built and tuned in the visual builder. You cannot recreate all of these from the API.

You will configure:

• When to show bots or workflows
• How conversations are routed and prioritised
• SLAs, assignment rules and escalation paths

Intercom's "Switching from Zendesk to Intercom" guide explicitly walks you through which workflows to set up as part of migration, and these are all UI steps.

Outbound messages, Series and campaigns

Outbound campaigns, Series, email broadcasts and in-app messages are configured via the Intercom UI. You choose audiences, triggers, delay steps and branching logic visually. The API can help you manage data behind segments, but the orchestration itself lives fully in the product.

Help center structure and styling

You may be able to import article content, but:

• Collections, sections and article ordering
• Help center branding, theme, colors, logo
• SEO settings and public URLs

All must be reviewed and tuned within the Articles and Help Center UI. Even with automatic Zendesk article import, you still adjust structure and layout manually.

App Store integrations

Most Intercom App Store apps are installed and configured through the UI. You connect external systems, grant permissions and adjust mapping settings there. The APIs then handle the underlying data movement, but the connection is a click-through setup.

Pre-migration setup in Intercom

This is the part people skip when they rush. The quality of your pre-migration setup usually decides whether your go-live is boring and calm, or a long night of fixing broken mappings.

1. Create the workspace and pick the right plan

Start by creating your Intercom workspace if you have not already, then make three decisions up front:

• Which plan and add ons you need for Support, Tickets, Fin or advanced automations
• Which region the data should live in (and confirm your data residency and compliance requirements are met)
• Who will be the main admin or owner of this migration

These are mostly one time decisions, but they determine which APIs you can call and which features your migration can lean on. 2. Design your schema and create data attributes

Before you import anything, decide how your old fields map to Intercom's data attributes. Use the Data Attributes API or the UI to create custom attributes on:

• Contacts (users, leads)
• Companies
• Tickets, if you use the Tickets product
• Conversations, if you want per conversation metadata

Intercom's docs recommend having attributes ready before you import people or tickets so mapping is clean and you do not lose context. 3. Import or create contacts and companies first

Next, bring in your people and accounts. Intercom's historical migration guide explicitly calls out that you should import contacts first, via CSV import in the UI or via the Contacts API.

Do the same for companies. Once users and companies exist, you can reliably attach conversations and tickets to them in later steps. 4. Set up channels and inboxes

Now configure your channels:

• Support email addresses
• Messenger on your website and in your product
• Any social channels you plan to use

Map them into Intercom inboxes. At this stage, you usually do not point production traffic at Intercom yet. You just confirm the plumbing so you are ready when cutover day comes. 5. Build teams, roles and high level routing

Create the teams that match your real world structure: Support, Sales, Billing, Escalations. Add teammates and assign them roles.

Then sketch the basic routing rules you will use after go-live, but keep aggressive automations disabled for now. Intercom's best practices guides suggest starting with simple assignment rules, then layering more complex workflows later. 6. Turn off noisy automations for the import window

Before you run any large imports:

• • Pause or limit outbound campaigns and Series
  • Disable CSAT or NPS messages that might trigger on old conversations
  • Reduce internal notifications so agents are not bombarded by alerts on migrated history

This keeps both customers and agents from getting spammed while you load old data

Migration Execution

This is where the data actually shifts.

• First run a sample migration of a small dataset of the messiest data you can find.
• Verify if the sample migration was successful and adjust the mapping and fix the script bugs before the full migration.
• Import contacts/leads, companies first. Make sure every conversation's requester exists.
• Import conversations and messages: each original ticket becomes a conversation in Intercom or a conversation with threaded messages, depending on your plan. Preserve timestamps, participants, attachments, message order.
• Assign conversations to correct owners or teams based on your mapping.
• Import attachments, tags, custom attributes, company links.
• Run your delta import to capture any new tickets from cutoff to go-live.
• Cutover the channels: forward email, switch chat widget, ensure new requests go into Intercom not the old system.
• Monitor API calls, handle errors, log failed records and plan manual fixes if needed.

Post-Migration Checklist

Data verification

Check counts: number of users, companies, conversations, messages, attachments in Intercom vs source.

Spot check a handful of old tickets: confirm who asked, how many messages in the thread, attachments, the final status.

Ensure you don't have orphan conversations (no user) or missing attachments.

Channel & workflow testing

Test new inbound tickets from all channels: email, chat, SDK if you use it.

Reply as an agent, confirm a customer reply threads correctly.

Test assignment, tags, internal notes, routing rules. Make sure notifications and triggers behave as expected.

Agent setup & training

Ensure all teammates have their roles, inboxes, permissions configured.

Train them, even if they were users in the old system, Intercom works differently. Walk them through the inbox view, conversation handling, tags, internal notes, companies view.

Final go-live cleanup

Switch off the old system or set it to read-only to avoid conflicts. Re-enable any workflows or campaigns you paused during migration.

Schedule a review after one week and one month to capture missed items, gather agent feedback, check for data discrepancies, fine-tune routing or fields.

Rollback and Contingency Planning

Migrations do not always go cleanly. Plan for failures before you start.

• Duplicate contacts — If contacts are created twice (e.g. because of a mismatched user_id or email), you can merge them via the Intercom UI, but at scale this is painful. Prevent this by enforcing unique identifiers during import and verifying lookups before creation.
• Conversations attached to wrong users — This usually happens when legacy IDs do not map correctly. Catch it in your sample migration. Once conversations are created, re-assigning them requires manual work or re-import.
• Partial import failures — If your script dies mid-run, you need to know where it stopped. Log every record with its source ID, Intercom ID, and status (success/fail/skipped). This lets you resume without re-importing already-created records.
• Rollback scope — Intercom does not have a "delete everything and start over" button. You can delete contacts and conversations via the API, but it is slow and rate-limited. For large migrations, it is faster to create a fresh workspace and re-run than to try to clean up a botched import.
• Keep the source system intact — Never decommission your old system until you have verified the migration. Keep it in read-only mode for at least a few weeks post-cutover so agents can reference records that did not transfer perfectly.

Common Mistakes and Pro Tips

• Historical message-by-message imports can be expensive in API calls and time. If you only need context, sometimes migrating a summary ticket is enough.
• Always map legacy user IDs in your import so contacts don't duplicate. Users are the key anchor in Intercom.
• Disable automated campaigns and high-volume outbound content during import. They can hit API rate limits or interfere with routing.
• Attachments often break because of file types or size. Validate that Intercom supports the file types you are migrating.
• Keep the old system live for a few days after go-live, but in read-only mode. Agents may need to reference tickets that didn't migrate perfectly.
• Do not underestimate agent training. A clean migration with no training still fails in practice because agents will struggle with a new UI and different workflows.