The Complete Guide to Migrating from Help Scout to Kustomer

Moving from Help Scout to Kustomer is a significant step toward a more unified view of your customer journey.

Making the switch requires careful planning, a bit of technical logic, and a solid understanding of how data flows between these two distinct systems.

Define Your Migration Scope

Before you begin moving data, you need to decide exactly what makes the cut. A successful migration is as much about what you leave behind as it is about what you bring with you.

What to Migrate via the API

Most of your core data will travel through the API to ensure accuracy and speed. This includes your customer profiles, company information, and the full history of your conversations.

Internal notes and file attachments are also supported through API methods, allowing your team to maintain context on complex cases.

Your Knowledge Base articles and categories can be migrated programmatically to keep your self-service resources intact.

What to Configure Manually

Some elements are unique to the way Kustomer operates and cannot simply be "mapped" over.

You will need to manually recreate your automation logic, such as workflows and routing rules, because the underlying triggers and branching logic differ between platforms.

Business schedules and specific brand settings also require a manual touch to ensure your service level agreements are calculated correctly from day one.

What to Archive

Not everything needs to live in your new active environment. Historical satisfaction ratings from Help Scout do not have a 1:1 functional map in Kustomer's active survey tool, so these should be archived as custom attributes on the conversation timeline instead of being imported into the satisfaction resource.

You might also take this opportunity to archive old, redundant tags or customers who have not interacted with your brand in several years to keep your new workspace clean.

Prepare Kustomer for Data Import

You must lay the groundwork in Kustomer before the first piece of data arrives. Think of this as setting up the infrastructure so that when your information lands, it knows exactly where to go.

• Define Users and Role Groups: Set up your agents and administrators first so that conversations can be assigned to the correct owners during the import.
• Establish Teams: Recreate your internal departments as Teams in Kustomer to maintain your routing structure.
• Configure Brands: If you manage multiple email signatures or help centers, define your Brands early.
• Create Custom Attribute Metadata: This is arguably the most important step. You must define the "slots" for any custom data coming from Help Scout, such as legacy IDs or specific customer preferences, before you can import that data.
• Set Up Business Schedules: Define your operating hours to ensure that conversation timestamps and metrics are handled accurately.
• Initialize Knowledge Base Structure: Create your Knowledge Base and its associated themes so the articles have a place to live.

Migrate Objects

The order of migration is critical. You cannot link a message to a conversation if the conversation container doesn't exist, and you cannot link a conversation to a customer if the customer profile hasn't been created yet. Follow this logical sequence for a smooth transition.

The Foundational Objects. Start by moving your Organizations and Users. In Kustomer, Help Scout Organizations become Companies.

Once the companies are in place, you can import your Customers. It is a best practice to store the original Help Scout Customer ID in an external ID field in Kustomer; this acts as a permanent link between the two systems.

The Knowledge Base. Next, move your help content. Help Scout uses a hierarchy of Collections and Categories.

Since Kustomer Knowledge Bases focus on Categories, a common workaround is to turn your Help Scout Collections into top-level Categories in Kustomer and nest the original Categories beneath them.

Once the categories exist, you can migrate the Articles themselves.

The Interaction History. Now you can move the bulk of your data. First, create the Conversation containers.

Once these exist, you can begin importing Threads as Messages and internal Threads as Notes. Attachments can be linked to these messages using Kustomer's attachment resource, which provides a temporary policy for secure file uploads.

Finally, apply your Tags to the conversations to ensure your reporting remains consistent.

Object Mapping Table

Field-Level Mapping Notes

Object-level mapping is necessary but not sufficient. Several fields require explicit transformation before import:

Handling Pagination During Export

Help Scout's API uses cursor-based pagination. When bulk-exporting conversations, the response includes a _links.next object containing the cursor for the next page. Your export script must follow this cursor chain until _links.next is null — do not rely on page-number offsets, as these will produce incomplete or duplicated result sets on large mailboxes.

For large accounts, export conversations filtered by modifiedSince date ranges to split the workload into manageable batches and reduce the risk of a single interrupted request losing progress.

Error Handling and Recovery

No migration runs cleanly on the first pass. Plan for partial failures from the start.

Log every API response. Store the HTTP status code, the Kustomer-assigned ID, and your source Help Scout ID for every write. This log is the foundation of your recovery strategy.

Idempotent retries via externalId. If a conversation import fails mid-run, the externalId field prevents duplicates on retry. Kustomer will reject a second write with the same externalId rather than creating a duplicate record. This only works if you set externalId on the initial request — retrofitting it later requires a separate update pass.

Detect partial conversation imports. A conversation can be created successfully while some of its messages fail to import. After the full run, query Kustomer for conversations where message count is zero and cross-reference against your source export to identify gaps.

Common failure patterns:

• 422 Unprocessable Entity on customer import: usually a malformed email array structure.
• 409 Conflict on conversation import: externalId already exists; safe to skip on retry.
• 404 when attaching a message: the parent conversation write failed silently; check your conversation creation log.
• Tag-related silent failures: the tag string in the payload does not match an existing tag in Kustomer. Pre-create all tags before importing conversations.

Pre-Migration Validation Checklist

Run these checks before starting any API writes:

• Export a full record count from Help Scout: total customers, conversations, messages, notes, attachments, and KB articles.
• Confirm all custom attribute metadata is defined in Kustomer before importing any customer or conversation records.
• Verify that all agent email addresses in Help Scout exist as Kustomer users; unmatched assignees will cause assignment failures.
• Pre-create all tags in Kustomer that appear in your Help Scout export.
• Disable Help Scout outbound webhooks.
• Confirm API credentials: Kustomer uses API key authentication passed as a Bearer token in the Authorization header.
• If your Kustomer plan has a production API quota, confirm whether bulk import calls consume the same quota as production traffic, and schedule the migration during off-peak hours if so.

Post-Migration Verification Checklist

Run these checks after the migration completes and before decommissioning Help Scout:

• Compare record counts: customers, conversations, messages, notes, and KB articles between source and destination.
• Spot-check a random sample of 20–30 conversations to confirm message threading, timestamps, and attachments are intact.
• Verify that conversations with closed status in Help Scout appear as done in Kustomer.
• Confirm that createdAt timestamps on customers and conversations match the Help Scout source values, not the import time.
• Check that KB articles are visible in the help center (requires a published Version record per article — see Insider Secrets).
• Confirm that no zero-message conversations exist unless they were zero-message in the source.
• Re-enable Help Scout webhooks only after cutover is confirmed and rollback window has passed.

Rollback Strategy

Before starting the migration, document your rollback threshold: the point at which you will stop, revert, and investigate rather than push forward.

Kustomer does not provide a bulk-delete endpoint for conversations, so rolling back a completed import is operationally expensive. The practical approach is to run the migration into a Kustomer sandbox or trial environment first, validate the output, and only execute against production once the process is confirmed clean.

If a production migration is partially complete and must be abandoned, use your import log to identify which records were successfully written. Do not re-run the full migration script — replay only the failed records, using externalId to prevent duplicates on records that did succeed.

Post-Migration Configuration

Once the data migration is complete, you need to activate the automation layer to make that data useful.

• Rebuild Workflows: Manually create your automations to handle incoming mail, tag conversations, or notify teams. Use conditional branching to replace Help Scout's linear workflow logic.
• Establish Queue Rules: Define how new conversations should be distributed to your agents using the Queue and Routing tools.
• Define Routing Criteria: Set the specific conditions that determine which team or agent receives a work item.
• Activate Satisfaction Surveys: Set up Kustomer's satisfaction tool to begin collecting new feedback on your migrated conversations.
• Configure Saved Searches: Recreate your Help Scout views as Searches so agents can easily navigate their daily tasks.

Insider Secrets

1. Mind the Rate Limits: Kustomer has different rate limits based on your plan. If you are a machine user performing a bulk import, you might hit limits of 300 to 2,000 requests per minute. At 2,000 RPM with an average of 3 API calls per conversation (create conversation, create message, apply tags), a 50,000-conversation migration will take a minimum of around 2.5 hours of continuous API writes, not counting export time or retry overhead.
2. The importedAt Shortcut: When creating conversations or customers, including an importedAt timestamp in your data body can sometimes bypass standard rate limits during large backfills. This behavior should be tested against your specific plan tier before relying on it in production.
3. KB Versioning is Mandatory: Simply creating an Article isn't enough to make it visible. You must also create a Version for that article to publish the content into the help center.
4. Preserve Timestamps with Admin Roles: If you want to keep the original "created" dates from Help Scout, you must use a token with administrative privileges; otherwise, Kustomer will set the creation date to the moment of import.
5. Audit Logs are Your Safety Net: If something goes wrong during the import, check the organization audit logs to see exactly what events were triggered and where the data flow might have stalled.
6. External IDs are Your Best Friend: Always map the Help Scout ID to an externalId in Kustomer. This makes it straightforward to troubleshoot and prevents duplicate records if you have to run your migration scripts more than once.

ClonePartner is a paid migration service. This guide reflects patterns encountered in migrations we have executed. Where claims about API behavior are made, verify them against the current API documentation for your specific Kustomer plan tier.

Further Reading:

• Kustomer
• Help Scout