See related
No related articles

Migrate from another platform

Last Update: Oct 2024 • Est. Read Time: 5 MIN
To check plan availability, see the pricing page.

Before you get started in Kustomer, you will want to migrate data from your preexisting support system. This task should be delegated to your technical resources since many technical decisions factor into a seamless transition to Kustomer.

Who can access this feature?
User typesAdmins can perform these actions.


In this article

Questions to answer before migrating

Before migrating, we recommend going through this checklist to answer the most important questions:

  • How many months of ticket/case history do you want to migrate?
  • Are there tickets with certain attributes you want to exclude from the migration?
  • Do I want to map certain fields in the source system to fit Kustomer’s flexible data model?
  • Do you want your migrated conversations to be marked "Done" for a clean slate, or should their status reflect the source system’s status?
  • If your source system’s API is being used for other services, how much of your rate limit do you want to dedicate to the migration?
  • Do you want to import file attachments into Kustomer or back them up to a third-party cloud storage provider?
  • Do you want to run a test migration?
  • How much time will you spend reviewing the migration results and doing any post-migration cleanup?
  • How do you want to handle assignments and authorship of messages/notes by users that you do not import to Kustomer?

Our API has been used to import data from Zendesk, Desk, Intercom, and Helpscout. We recommend importing users (those using Kustomer) before migrating ticket data.

Migrate users

You will want the outgoing message authorship and agent ticket assignments of your migrated data to reflect your legacy data’s authorship and assignment. For information on importing agents from your legacy system, see Add and authenticate users. Once your users are set up, you will want to create a mapping to map their source system’s ID to their Kustomer’s ID. For example:

{

  114580091813: “591909806b184000119732db”,

  115173036133: “583dc762a98be3110034436a”,

  115173065213: “597f622b42a75a0015ba768b”

}

Migrate tickets

Migrating an individual ticket can be divided into two phases. Phase one involves fetching all of the details you need from your source system. Phase II involves transforming the fetched data and posting it to Kustomer.

Phase I - Fetching ticket details from source system

The type and number of requests you need to make to the source system for a single ticket depend on the source system’s API and the data you want to extract. To start, we recommend fetching the ticket details (subject, status, created at, custom fields, etc.), messages, and the associated customer (contact, end-user, etc.) for each ticket.

Phase II - Transforming fetched data and post to Kustomer

Most of your data migration script will be spent in this phase. You must transform your data to match our API's corresponding JSON data model. When posting your data, your requests must follow an order of operations. If you are creating conversations in Kustomer, you must associate the conversation with a customer within Kustomer. Likewise, you will need a conversation to thread messages and notes together.

Here’s a summary of the order of requests we recommend:

  1. Find customer - If the customer already exists, update the customer or continue without doing anything. If they do not exist, you must create the customer.
  2. Find conversation by external ID - If the conversation does not exist, create it on the found or created customer’s profile. If the conversation does exist, update it if there have been changes in the source data since the conversation was created/last updated.
  3. For each message (and note), find or create the message/note by external ID. If the message/note does not exist, create it. If it does, continue to the next message/note without doing anything.

Note: We recommend that imported tickets should be excluded from Kustomer’s reports. To do so, add importedAt: new Date() (JavaScript) to your request body for all imported objects. This flag will also prevent imported objects from triggering notifications to your users.

Find or create a customer

If you have multiple tickets for one customer, those imported conversations should live under one customer profile. Your approach to finding or creating a customer depends on if you are saving the customer’s email, phone number, or both, in your source system. When you create a customer, you can also include an arbitrary external ID that references their ID in your legacy system. In Kustomer, a phone number, email or external ID can only belong to a single profile across all your customers.

Note: Attempts to create or update a customer with an email or phone number that already exists in Kustomer will fail with a duplication error. Be aware that some ticketing systems might allow multiple customer profiles with the same email or phone number! 

Useful endpoints for existing customers

Using a combination of these endpoints should help you determine if the customer already exists in Kustomer:

Find or create a conversation

It's important to store your legacy systems’ ticket IDs in the newly created conversation’s external ID field. The external ID field ensures that duplicate conversations aren't created and that updates are patched to the correct conversation in situations such as:

  • If you run a second incremental migration and a ticket has been updated in your source system since you first imported it into Kustomer.
  • If your script crashes and you need to restart.

Useful endpoints for conversations

If you want to migrate the agent assignment for the ticket, set assignedUsers to the respective user’s mapped ID based on the user mapping you generate. For example, if the legacy ticket is assigned to an agent with ID 114580091813then the assignedUsers field in your post to Kustomer should be assignedUsers: [“591909806b184000119732db”]

{

  114580091813: “591909806b184000119732db”,

  115173036133: “583dc762a98be3110034436a”,

  115173065213: “597f622b42a75a0015ba768b”

}

Find or create messages and notes

Messages and notes should follow the same find or create by external ID convention described above.

If you want to migrate the authorship for an outbound message or note, set createdBy of the message to the respective user’s mapped ID based on the user mapping you generate. For example, if the legacy message/note was authored by an agent with ID 114580091813then the createdBy field in your post to Kustomer should be createdBy: “591909806b184000119732db”

{

  114580091813: “591909806b184000119732db”,

  115173036133: “583dc762a98be3110034436a”,

  115173065213: “597f622b42a75a0015ba768b”

}

Best practices

  • Add a tag to the conversations you are importing to easily build a saved search to view your migrated conversations in Kustomer or exclude them from other searches.
  • Store the ticket's URL in your source system as a custom field in Kustomer. Your users can use this URL to link back to the source system.
  • Keep a log of ticket IDs that resulted in an error when trying to post to Kustomer. If you successfully migrated 99,500 tickets but 500 failed because of an edge case, you can use your error logs to troubleshoot and adjust your migration script.
  • If your source system has a “search tickets” endpoint, you can build a query to determine the tickets you will import.
  • When you start your script, tickets will probably continue to be created and updated in your system. After your initial migration ends, you must run incremental migrations (a.k.a. deltas) until your team completely switches to Kustomer.

FAQ

Q. Why am I missing tickets after an import?

You should provide your data migration engineer with the ID of the source ticket you expected to see in Kustomer. That should be more than enough for them to troubleshoot.

Q. Can I sync conversations from Kustomer back into my legacy system?

Yes, you can fetch conversation data from Kustomer and post it to your source system’s API. However, we cannot support you in this endeavor.

Related topics