The Complete Guide to Migrating from Kustomer to Intercom

This guide covers the technical process of migrating from Kustomer to Intercom, including API-level specifics, data mapping, known failure modes, and what cannot be migrated.

It assumes you have API keys for both platforms, admin access in Intercom, and familiarity with REST APIs. Migration duration depends heavily on data volume — a workspace with 50,000 conversations behaves very differently from one with 5 million.

Define your migration scope

What to migrate via the API

The heavy lifting of your migration involves high-volume data that requires programmatic transfer.

This includes your core entities like Customers and Companies, as well as the detailed history of your interactions. Conversations, the Messages within them, and the private Notes shared between your team members are all handled through automated imports.

Your Knowledge Base Articles and Categories, along with KObjects (Kustomer's custom data entities that let you model domain-specific objects like orders, subscriptions, or shipments outside the standard Customer/Conversation schema), will be moved this way to preserve the depth of your existing resources.

What to configure manually

Certain elements are better handled through the user interface to ensure they align with the Intercom structure.

You will need to manually invite your Users, who become Admins in your new workspace, and organize them into Teams.

Functional tools like Shortcuts, which act as Macros, and the specific logic for your Workflows must be rebuilt to take advantage of Intercom's specific automation capabilities.

Finally, because snooze definitions and past Satisfaction survey responses do not always have a direct data path, these should be set up as new configurations.

What cannot be migrated

Some Kustomer data has no structural equivalent in Intercom and cannot be migrated regardless of approach:

• Historical satisfaction survey responses — Kustomer's satisfaction model does not map to Intercom's Conversation Rating structure. You can export these for reference, but they cannot be imported as native ratings.
• Snooze state and history — Active snoozes and their historical log have no import path. Snooze actions must be configured fresh.
• Workflow execution history — Kustomer tracks which workflows fired on which conversations. This audit trail has no Intercom equivalent.
• Audit logs — Kustomer's internal audit trail is platform-specific and cannot be transferred.
• Nested KObject relationships — If your KObjects reference other KObjects (e.g., an Order KObject linked to a Shipment KObject), Intercom's Custom Object Instances do not support the same relational depth. You will need to flatten or restructure these.
• Conversation SLA metadata — SLA policy assignments, breach history, and timer data from Kustomer do not have a direct import target in Intercom.

What to archive

It is often wise to leave some data behind to keep your new workspace clean. Audit logs, temporary tracking events, and conversation data older than two years are prime candidates for archiving rather than active migration.

You can export this data into a secure storage format for compliance or historical reference without cluttering your daily support environment.

Prepare Intercom for data import

Before you start pushing data into the system, you need to set the stage by recreating your organizational framework.

• Create Data Attributes for both contacts and companies to mirror the Custom Attributes you used previously.
• Manually set up your Teams so that conversations can be assigned to the correct groups immediately upon import.
• Invite your teammates as Admins and assign them to their respective teams to maintain accountability.
• Establish your Help Center Collections to serve as the structural containers for your incoming knowledge base articles.
• Define your Tag list so that categories can be applied to customers and conversations as they arrive.

Migrate objects

The migration follows a specific logical sequence. You must build the foundation before you can populate the history. Structural metadata first, then people, then interactions. Violating this order — for example, importing messages before their parent contacts exist — results in orphaned records that cannot be linked after the fact.

Data Mapping

1. Structural Metadata and Definitions: First, you move your Custom Attributes and Tags. In Intercom, these are created via POST /data_attributes and POST /tags respectively. You also define the schemas for your KObjects, which will exist as Custom Object Instances.
2. People and Organizations: With the attributes ready, you import Companies via POST /companies and then Customers via POST /contacts. It is important to move companies first so that you can properly associate individual customers with their organizations during their import by including the company_id in the contact payload.
3. Interaction History: Once your contacts exist, you can begin importing Conversations via POST /conversations. Because Intercom views communication as a series of parts, you reconstruct message threads by calling POST /conversations/{id}/reply for each message, replying on behalf of either the admin or the customer. Private Notes are attached via POST /contacts/{id}/notes.
4. Knowledge and Content: Finally, you move your support content. You populate the previously created Collections with your migrated KB Articles via POST /articles, ensuring that internal links and formatting remain intact.

Post-migration validation

Before you consider the migration complete, run these checks:

• Record count comparison — Compare total counts of contacts, companies, conversations, and articles between Kustomer exports and Intercom. Any discrepancy signals dropped records.
• Conversation thread spot checks — Pick 20–30 conversations at random across different date ranges. Verify that message order, sender attribution, and timestamps are correct.
• Knowledge base rendering — Open every migrated article in the Help Center. Check for broken images, dead internal links, and formatting that did not survive the HTML conversion.
• Custom attribute completeness — Run a sample of contacts through the Intercom UI and verify that custom data attributes populated correctly, especially date fields and multi-select values.
• Tag integrity — Confirm that tags applied in Kustomer appear on the correct contacts and conversations in Intercom.
• KObject / Custom Object verification — If you migrated KObjects, verify that Custom Object Instances are linked to the correct contacts and that field values transferred accurately.

Post-migration configuration

After the primary data is in the system and validated, you must reconnect the "wiring" that makes your support operation run.

• Rebuild your Shortcuts as Macros, ensuring any dynamic text placeholders are updated to the new syntax.
• Configure your Workflows and Series to replace your old automated logic, using Intercom's branching paths.
• Set up your Conversation Rating settings to begin collecting new satisfaction data from customers.
• Re-establish your Business Schedules to ensure that your "away" and "office hours" logic works correctly.
• Enable your Snooze options so that agents can put conversations on hold with the correct intervals.

Edge cases and failure modes

1. Respect the rate limits: While migrating, you will encounter limits on how many updates you can make to a single object in a short window. A single contact can usually be updated 600 times in 10 minutes, but other objects like companies or messages are limited to 100 updates in that same timeframe. When you hit a limit, the API returns a 429 Too Many Requests response with a Retry-After header. Your migration script must handle this gracefully — implement exponential backoff or simply sleep for the duration specified in the header. Failing to handle 429s will result in silently dropped records.

2. External ID is your best friend: When creating contacts or companies, always include an external_id from your original Kustomer database. This allows you to perform reliable lookups later via GET /contacts?external_id={id} if you need to update a record or link it to a new interaction without creating duplicates. Without external IDs, you will need to match on email address, which fails for contacts with multiple or missing emails.

3. Deduplication strategy: Before importing contacts, query Intercom to check whether a contact with that email or external ID already exists. If it does, decide your merge strategy upfront: update the existing record, skip it, or create a log entry for manual review. Kustomer exports frequently contain duplicate email contacts — especially when customers have contacted support from multiple email addresses that were later merged. If you do not handle this before import, you will create duplicate contacts in Intercom that are difficult to clean up after the fact.

4. Timestamp preservation: You can set historical creation dates for imported data using the created_at parameter on supported endpoints if you have administrative privileges. This ensures that a conversation from three years ago still looks like it happened three years ago in your history. If you omit this parameter, all imported records will appear as if they were created on the import date, destroying your historical timeline.

5. The message threading workaround: Since you cannot just "upload" a message, you have to use the reply functionality to build a conversation history. You call POST /conversations/{id}/reply on behalf of either the admin or the customer to reconstruct the thread. The type field in the payload determines the sender role. Messages must be imported in chronological order — importing them out of sequence results in a garbled conversation view.

6. Data attribute type mismatches: Kustomer Custom Attributes often use specific suffixes like Num or Bool to define data types. If you create a Data Attribute in Intercom as a string when the original was a number, downstream filtering and reporting will break. Map types explicitly before import and validate a sample batch before running the full migration.

7. Kustomer data quality issues to watch for: Common problems in Kustomer exports include null external IDs on older contacts, duplicate email addresses across merged customer records, malformed timestamps on conversations that were imported into Kustomer from a previous platform, and KObject schemas that reference deleted or renamed custom attributes. Run a data quality pass on your Kustomer export before attempting any import.

8. Importing messages before contacts exist: If your migration script attempts to create a conversation or reply referencing a contact ID that does not yet exist in Intercom, the API will return a 404 or silently create an anonymous conversation. These orphaned conversations cannot be retroactively linked to the correct contact. Always complete the full contact import and verify counts before starting the conversation import.

9. Running a parallel migration with a live team: If your support team is actively working in Kustomer during the migration, you risk creating duplicate conversations — one in Kustomer and one in Intercom. The standard approach is to migrate historical data first with a clear cutoff date, then run a delta sync for any conversations created between the initial export and the final cutover. Your team should not start working in Intercom until the delta sync is complete and validated.

Summary

By following this logical order and distinguishing between what can be automated and what requires a human touch, you ensure that no customer detail is lost.

Take your time with the preparation phase, as a well-defined schema makes the actual data transfer much smoother. Once your workflows are rebuilt and your team is settled, the migration is complete.

If you'd rather focus on your revenue instead of wrestling with mapping sheets and pagination loops, ClonePartner can handle the full migration for you. Every project gets a dedicated engineer who understands the nuances of both APIs and ensures zero downtime.

Further Reading:

• Kustomer API Reference
• Intercom API Reference