Migrate from another platform
Learn how to migrate your data from your pre-existing support system.Articles
Migrate from another platform
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 articleQuestions to answer before migratingMigrate usersMigrate ticketsFind or create a customerFind or create a conversationFind or create messages and notesBest practicesFAQQuestions to answer before migratingBefore 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 usersYou 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 ticketsMigrating 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 systemThe 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 KustomerMost 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: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.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.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 customerIf 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 customersUsing a combination of these endpoints should help you determine if the customer already exists in Kustomer:Get customer by external IDGet customer by emailGet customer by phone numberFind or create a conversationIt'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 conversationsGet conversation by external IDCreate conversationUpdate conversation attributes 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 114580091813, then the assignedUsers field in your post to Kustomer should be assignedUsers: [“591909806b184000119732db”]{ 114580091813: “591909806b184000119732db”, 115173036133: “583dc762a98be3110034436a”, 115173065213: “597f622b42a75a0015ba768b”}Find or create messages and notesMessages and notes should follow the same find or create by external ID convention described above.Get a message by external IDCreate messageCreate note within conversationIf 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 114580091813, then the createdBy field in your post to Kustomer should be createdBy: “591909806b184000119732db”{ 114580091813: “591909806b184000119732db”, 115173036133: “583dc762a98be3110034436a”, 115173065213: “597f622b42a75a0015ba768b”}Best practicesAdd 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.FAQQ. 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 topicsAdd and authenticate usersData model overviewPlatform terminology comparison guide
Now that you've made the switch, it's important to learn the key terms used in Kustomer and how they compare to your previous platform.ConceptKustomerZendeskSalesforce Service CloudConversation ObjectConversationTicketCaseCompany ObjectCompanyOrganizationAccountCustomer ObjectCustomerUser/CustomerContact/CustomerCustom ObjectKObjectCustom Object BetaCustom ObjectShortcutShortcutMacroMacroDynamic TextDynamic textDynamic TextMerge FieldsWorkflowWorkflowTriggers, AutomationsRules/WorkflowTwitterTwitter MessagesTwitter TicketsTwitter CasesSnooze StatusSnoozePending, On HoldPendingDone StatusDoneSolvedResolvedAgent WorkspaceAgent WorkspaceAgent InterfaceAgent ConsoleCollaboration UsersCollaboratorsLight AgentsFlex timeTeamsTeamsGroupsGroupsSearchesSearchesViewsFilters / QueuesPush WorkQueues & routingPlay ModePlay / Omni-channel routingInternal NoteNoteNoteNote / ChatterReplyReplyExternal ReplyResponseProactive chatProactive chatChat TriggerAutomated Chat InvitationTagsTagsTagsLabels / NAKnowledge BaseKnowledge baseZendesk GuideKnowledgeObject ViewsObject Views / Klass ViewsLayoutsPage LayoutsIntegration ViewInsight CardZen PluginCanvasImport data from Zendesk
Are you transitioning out of Zendesk? Kustomer offers an automated import tool that connects to your Zendesk account to import your historical data into our platform. This importer aims to take tickets, tags, users, and groups from Zendesk, and transition them into conversations and other corresponding fields in Kustomer.To help you through this process, we've created an Import Wizard that walks you through the entire data migration and asks you how you want your Zendesk data to come into Kustomer.Who can access this feature?User typesAdmins can access the Data Import page.You can access the importer in Kustomer by going to Settings > Administration > Data Import. On the settings page, click the Learn More link to learn more about our data import features and watch an overview video.Data Connect
Data Connect allows administrators to sync objects from another system into Kustomer through a guided setup. This feature makes it easier than ever to continuously capture data from an external source without needing to manually build a custom workflow.During the Data Connect setup, we'll ask you to choose which objects to sync and how you want fields from your external platform to match with Kustomer fields. Then, our wizard will use your selections to create a workflow automation to continuously capture data from your target source.Who can access this feature?User typesAdmins can access these settings pages.In this articlePrerequisitesOverviewCreate the KlassCreate the webhookData Connection Wizard Walkthrough1. Prepare2. Connection Details3. Configure WebhookExample JSON payloads4. Match Fields5. ReviewPrerequisitesThis feature requires understanding of advanced technical concepts including webhooks, and admins will need to provide a JSON payload from the target external platform to configure sync.Admins will also be activating an app-created workflow during the setup process. It is not required to understand or customize this workflow to activate it, but if you require further customization of this workflow, you will either need to be familiar with the basics of Workflow automations or contact Kustomer Support to make the desired changes. Learn more about this concept in Workflows Overview.OverviewYou can create data connections and view the status of any existing data connections in Settingsunder Administration > Data Import > Data Connections.To set up Data Connect, select the Add Data Connection button above the connections table. This will open our setup wizard which walks you through a 5-step process for activating a new data connection.Here's a general overview of the steps you'll see during setup:Prepare: Review best practices for syncing data.Sync Details: Set the name and high-level settings for the connection, including what you want to sync and what custom klass to connect data to.Configure Webhook: Choose the webhook that your external system is posting data to, and add a sample JSON payload so we can start configuring your optimal connection settings automatically.Match Fields: Correlate fields from your JSON with selected Klass attributes in Kustomer.Review: Confirm all of your settings are correct before you initiate the data connection.Once Data Connect is set up, the connection will offer a continuous sync of data from your existing system to Kustomer. The objects you selected will be created on a continuous basis for as long as the connection remains active.Create the KlassData Connect requires two components to be set up in your Kustomer organization:A Klass for your objects to sync toAn inbound webhook in Kustomer, which your external system will POST toIf you don't already have a Klass set up for use with this data connection, start by creating one. Learn more in our help guide Define custom attributes in Kustomer.Create the webhookIf you don't already have a webhook ready to use for this data connection, here's how you'll create one.To create an inbound webhook:In Kustomer, go to Settingsand select Platform > Inbound Webhooks.Select Add Inbound Webhook.Fill out the name and description of the new webhook.Note: We always recommend as a best practice that you use clear and illustrative names and descriptions, so that it's easy to know what function this webhook performs if another member of your team reviews it at a later date.For the type of the webhook, select Web.Then, select Create to save the new webhook.With the webhook set up, you're now able to begin walking through the Data Connect setup wizard. Data Connect Wizard Walkthrough1. PrepareOn the first page of the wizard, you'll see a variety of recommendations that will be useful to keep in mind as you plan your data connection:Do you know what you want to sync?This guide will allow you to sync data from your existing system to Kustomer. In order to sync properly, you will have to create a Klass for the objects you wish to sync. It is recommended that this Klass is created before starting the sync.If you're following the steps in this help article, you'll have already set this up.Have you created a webhook?To start syncing data, you will need to create a webhook in Kustomer and then POST to this webhook from your system. In order for the sync to run properly, your system needs to be sending data to the webhook URL.If you're following the steps in this help article, you'll have already set this up.Do you have a sample JSON?To properly match the fields between your system and Kustomer, you will need a sample JSON data payload that contains the data that will be sent from your system.You can find an example of what this looks like in our help article Data payload examples.2. Connection DetailsOn the second page of the wizard, you'll manage some of the high-level details and settings for the data connection.You'll set the name of your sync, which is how you'll distinguish this data connection from other import sources in Settings. The name you set cannot be changed after you create it here, outside of creating an entirely new data connection with a different name.Here you'll also set whether to sync Customers, or Customers & Custom Objects, as well as picking the custom klass to sync to.3. Configure WebhookIn this step, you'll choose the webhook that your system is posting data to. If you didn't already create a webhook earlier in this guide, you can use the Create New Webhook link in the wizard to start setting one up.You'll also need to provide a sample JSON payload. We'll use your payload to start matching fields between your external system and Kustomer, though you'll customize the rest of the fields yourself in the next step.If the JSON sample can be read successfully, you'll see a Valid JSON confirmation message above the code block. Once you have a valid JSON check, you can select Save and Continue to proceed to the next step.If after pasting the JSON you receive an Error Parsing JSON message, this means you'll need to check your formatting and try again before you can continue with setup.Example JSON payloadsYou can find an example of sample JSON data in our help article Example Data Payloads. Follow the guidance in that article to ensure that the JSON file is formatted correctly.4. Match FieldsIn this step, you'll now match the fields from the JSON payload and your selected Klass attributes.In the top section of this screen, you'll match one or more fields from the JSON to use as a unique identifier for imported customers. Based on your selections earlier in this wizard, you'll be required to match at least one of the External ID, Phone, or Email fields for Customers, or External ID for Custom Objects.Then, you'll match the remaining customer fields to Klass attributes in Kustomer.5. ReviewIn the final screen of the wizard, you can review and confirm all of the settings for your data connection before you activate the sync.Once you're ready to start syncing data, select Initiate Connection at the bottom of the window.Import data from CSV
Moving to Kustomer from another platform? We offer an automated import wizard that can pull data into Kustomer from a CSV file. Through our import tool, you can import customers, users, teams, or companies using CSV, a common file type that is offered as an export option in most systems. To help walk you through this process, our import wizard will step you through the entire data import and asks you how you want your CSV data to come into Kustomer. This article will walk through using the CSV Import tool and cover every step in the process you'll see along the way, as well as share some CSV template files to get some best practices.Who can access this feature?User typesAdmins can access the Data Connect page.In this articlePrerequisitesOverviewCSV sample templatesFormatting tips and recommendationsImport Wizard walkthrough1. Prepare2. Configure3. Upload CSV4. Link Data5. Match Fields6. Review CSV ImportReview import resultsImport more data with the same settingsPrerequisitesOur importer can import documents saved as comma-separated values (CSV). Before you can begin in Kustomer, you'll need to find a way to export from your current system to a CSV file saved in UTF-8 format. Please check with your current provider's help resources for best practices on exporting to CSV from their system.OverviewHere's a general overview of the steps you'll see during the import:Prepare - Review best practices for importing.Configure - Set the name and pick what type of data to import: customers, users, teams, or companies.Upload CSV - Upload your CSV file for processing.Link Data - Depending on your choices from the Configure step, tell our importer how you'd like to start connecting your data to Kustomer at a high-level. This will start the matching process that's continued in the next step.Match Fields - Pick how your CSV fields will correspond to fields in Kustomer.Import CSV - Review a summary all of your import settings, and then start the import once you're ready to go.CSV imports are usually pretty quick, so you should be able to tell how the import went without too much delay. We'll send you an email when the import completes, and you'll be able to view a summary of imported data or any issues encountered from the Import Results screen.If you're satisfied with these results, you can then reuse your import settings on future CSV imports. To import another CSV file with the same settings, use the menu icon next to the finished import on the Data Import Management table, then select Create New Import with Same Settings.Once that's done, you can start using Kustomer with your historical data.CSV sample templatesFor optimal results, try to match your CSV formatting and headers to the sample documents provided below. These pre-formatted example templates demonstrate the optimal file organization for you to get a successful result during your import.Customers sheetTeams sheetUsers sheetCompanies sheetFormatting tips and recommendationsHere are some useful considerations to keep in mind for your CSV:Phone numbersIf a country code is not provided, we will default to the country code for the U.S. (+1).Date formatsDates should be written in YYYY/MM/DD HH:MM:SS format. Use slashes / or dashes - as separators for date. For example, 2021/03/26 07:58:30 or 2021-03-26 07:58:30.Location formatsTo add multiple addresses for a customer, separate inside each location cell with a semi-colon ;. If the address contains a comma , wrap the comma in double quotations ",". Unsupported fieldsThe importer is currently unable to support uploading information to the following Kustomer fields:CustomerFacebookIdsInstagramIdsSocialsSharedSocialsURLs (Websites)CompanyDomainsSocialsURLs (Websites)Matching logicThe importer attempts to match records against existing data using the following rules:Customer: First tries to match on Kustomer ID, then External ID, then email, then phone # (if multiple emails or phone numbers match, the record will be skipped)Company, Team, User: First tries to match on Kustomer ID, and then External ID.Import Wizard walkthrough1. PrepareOn the first page of the importer, you'll see a variety of recommendations that will be useful to keep in mind as you plan your migration:Have you planned out your import?During this wizard, you'll be asked to match data from your CSV to fields in Kustomer. A lot of thought and preparation will need to go into this process, which largely depends on the data you're importing and your company's needs in Kustomer.We recommend that you use a notepad to pre-plan and solidify your field matching decisions in advance before diving deeply into the import process itself.Remember: you can save and exit the wizard after any step, then return later once you're fully prepared to continue.Are you planning to link data?Kustomer supports different data relationships depending on what you’re importing.Customers can be linked to Companies, and Users can be linked to Teams. Custom Objects (like Orders) are required to be linked to Customers.Depending on your import choices, you'll be asked to provide certain data fields in your import to use when linking data fields.Do you want automations to run on your import?Do you have any business rules or workflows that act on imported tickets? You should review your automations, and consider temporarily turning some of them off during the import process to avoid any unwanted automations.Or, you can add a conditional step to your workflow to avoid running when a new kConversation contains an importedAt key. Learn more about creating a workflow that filters for imported conversations in Common workflow fields.What file types am I able to import?Our importer can import documents saved as comma-separated values (CSV). CSV is a common file type that is offered as an export option in most systems.2. Configure ImportOn the second page, you'll be able to modify the name of the import, and decide what data to bring into Kustomer. For each import, you'll pick one property to focus on—you can import customers, users, teams, or companies.We'll automatically generate an import name for you, but you can specify another name if you wish.You'll select whether to import only new data, or import new data and update existing data. If you choose to update existing data, we'll attempt to match data from the CSV to existing attributes in Kustomer, which can overwrite existing Kustomer data.Should I update existing data or only import new data?Import new data:Requires minimal setup.The most appropriate option if your team has already started using Kustomer — for example, if you plan to only import CSV to backfill data from another system, but don't want to overwrite newer data your agents have been adding in.If you've exported historical data from an ecommerce store, and you only want to import new customers that aren't already in Kustomer.Update existing data:Another system is your primary source of truth for customer records.There are partial records in Kustomer that should be updated.Last, you'll select at a high level which type of data to import — customers, users, teams, or companies. To help you optimize your CSV file for import, the wizard will present you with pre-formatted CSV sample templates that show optimal formatting for the type of data you've chosen.When ready, Save and Continue to the next step.3. Upload CSVIn this step, you'll upload to us the actual CSV document you want to import from. Your file must have a .csv file extension and be smaller than 10MB.It will take a few minutes to upload and process your CSV file. Do not leave the upload page until you see the confirmation that the process was successful—otherwise the upload will be interrupted and you'll need to submit the file again.If at any point you need to switch to a different CSV file, you can return here to Step 3 and select Upload CSV again to replace the uploaded document and use a different file.When ready, Save and Continue to the next step.4. Link DataDepending on your choices earlier in the Configure step, you'll be asked to take additional action on this step to prepare for data matching.For example, if you opted earlier to link Customers with Companies, and then chose to match using an External ID, you'll be asked to pick the field from your CSV to match with the Company External ID.If your import doesn't require any data linking, you'll be notified that you can continue to the next step.5. Match FieldsThe largest task in the import wizard is the Match Fields screen. This is where you'll tell Kustomer how data from your CSV should match to metadata fields in Kustomer.We'll attempt to match fields automatically based on your selections earlier in the wizard, but take a moment to review all of the matching and confirm any additional fields. If there's a field missing that you need, you can use the link at the bottom of the screen to Create more attributes in the Klasses Settings.If you have more fields in your CSV than you wish to import into Kustomer, you can skip over any fields you wish to omit from the import.6. Import CSVIn the final step, you'll review your CSV import configurations before starting the actual import. This will be your last chance to confirm and make changes to this import before starting the import process.From the Review screen, you can select the Pencil icon next to any property to travel back to that step in the wizard to make changes.When you're ready to finally start the import, select Import CSV in the bottom corner. This will start the import, and you'll receive an email notification when the import completes.Review import resultsCSV import shouldn't take very long to complete, but you will receive an email whenever a CSV import finishes processing. This email will contain a link to visit the Import Results screen. You can also get to the results screen from the Data Import table by clicking the link in the tooltip after hovering your cursor over the status label.On the Import Results page, you can find a summary of how much data was imported, as well as links to view the imported data. Import more data with the same settingsAfter your first full import is complete, head back to the Data Import Management settings at any time to run an additional import with the same settings. If you're satisfied with the results of your first import and have more data to bring in to Kustomer, you can reuse the same settings to import subsequent CSV files.To import new data:Go to Settingsand select Administration > Data Import.Locate the earlier full import in the list, and select the More icon to the right.Select Create New Import with Same Settings.A wizard will appear with your earlier settings preselected. You can reuse this option as many times as you'd like to continue adding data into Kustomer from CSV.
Still need help? Contact Us