Kustomer to Zendesk Migration: The CTO's Technical Guide

Migrating from Kustomer to Zendesk is a data model translation problem. Kustomer stores customer interactions as a continuous, chronological timeline — every email, chat, note, and custom object (KObject) renders in a single stream per customer. Zendesk operates on discrete tickets: each conversation becomes an independent ticket with its own comment thread, status, and lifecycle.

There is no native migration path between these two platforms. No import wizard, no built-in connector. Kustomer's CSV export is a reporting feature capped at 30-day windows, and Zendesk's native data importer handles users, organizations, and custom object records — not full ticket history. If you need real support history in Zendesk, the practical path is Kustomer API extraction plus Zendesk Ticket Import API loading. (help.kustomer.com)

This guide covers the exact object mapping, API constraints on both platforms, extraction strategies, and the failure modes that derail teams mid-migration. If you're evaluating the technical feasibility of this move, start here.

For a broader pre-migration framework, see the Zendesk Migration Checklist. For general scoping guidance, see the Help Desk Data Migration Playbook.

Why Migrate from Kustomer to Zendesk?

The most common drivers we see across migration projects:

• Ecosystem breadth. Zendesk's marketplace has 1,500+ integrations. Kustomer's is significantly smaller. Teams that need tight connections to Jira, Salesforce, or Shopify often find Zendesk's native integrations more mature.
• Ticketing scale and reporting. Zendesk's ticketing model is purpose-built for high-volume, multi-channel support with mature SLA enforcement, CSAT surveys, and Explore analytics.
• AI capabilities. Zendesk's investment in AI (Answer Bot, Intelligent Triage, AI Agents) is tightly coupled to its ticketing model and Help Center content.
• Cost predictability. Kustomer's per-conversation pricing can spike unpredictably during peak volume. Zendesk's per-agent model is more predictable for budget planning.

The core technical challenge is translating Kustomer's timeline-centric data model into Zendesk's ticket-centric model without losing conversation context or breaking relationships. (help.kustomer.com)

Kustomer vs. Zendesk: Data Model and Object Mapping

Before writing any migration code, you need a clear map of how objects translate between the two platforms.

Core Object Mapping

Field-Level Mapping Detail

Do not assume status names, picklist values, or team semantics map 1:1. Preserve source IDs everywhere for idempotency and rollback. (help.kustomer.com)

Handling Custom Klasses (KObjects) → Zendesk Custom Objects

Kustomer Klasses define schemas for custom data objects — orders, subscriptions, shipments — with custom attributes linked to customer records. Instances of these Klasses are called KObjects.

Zendesk Custom Objects serve a similar purpose but have hard structural limits:

• Each custom object supports a maximum of 100 fields (standard fields excluded)
• Accounts cannot exceed 50 million custom object records total
• Each record has a maximum size of 32 KB
• Suite Team and Growth plans allow only 5 lookup relationship fields per object; Professional and above allow 10

If your Kustomer instance uses Klasses with more than 100 custom attributes, you'll need to split or flatten the schema before import. Some Kustomer Klasses belong in custom fields rather than standalone Zendesk custom objects — especially if the data is simple or rarely queried independently. (developer.zendesk.com)

Migration Approaches: DIY vs. Tools vs. Managed Service

Every viable approach falls into one of five buckets. The right one depends less on raw record count and more on whether you need threaded history, custom Klasses, live-team cutover, and auditability.

1. CSV Export/Import

Export Kustomer data via reporting exports or saved searches as CSV files, then format and import into Zendesk using the admin CSV import for users and organizations.

• When to use: Small datasets (<5,000 records), simple object structures, no custom Klasses.
• Pros: No code required. Fast for basic user/org data.
• Cons: Kustomer's native export is a reporting feature capped at 30-day windows. Saved search exports are capped at 50,000 rows and only cover the last 2 years. Zendesk's CSV import handles users and organizations — not tickets. (help.kustomer.com)
• Scalability: Small datasets only.

2. Custom API Scripts (DIY ETL)

Build scripts that extract data from Kustomer's REST API, transform it to match Zendesk's schema, and load it via Zendesk's Ticket Import API (/api/v2/imports/tickets).

The Ticket Import API is the only Zendesk endpoint that lets you create a ticket with multiple comments and custom timestamps in a single request — essential for preserving conversation history. (developer.zendesk.com)

• When to use: Engineering teams with spare capacity and complex data models.
• Pros: Full control over mapping logic. Can handle Klasses, attachments, and edge cases.
• Cons: Significant engineering investment (typically 3–6 weeks for a senior engineer). Must handle rate limiting, pagination, retries, and error recovery manually.
• Scalability: Depends entirely on implementation quality.

3. Self-Serve Migration Tools (e.g., Help Desk Migration, Import2)

SaaS platforms that connect to both APIs and map standard fields automatically through a UI wizard.

• When to use: Standard migrations with basic field mapping, limited custom objects, under 50,000 total records.
• Pros: Lower upfront cost. Handles common objects (users, tickets, comments) without code.
• Cons: Automated tools frequently experience timeouts and failures with large datasets (500K+ tickets). Custom Klass/KObject migration is typically unsupported. Limited control over transformation logic. Some tools exclude side conversations and archived tickets. (help.import2.com)
• Scalability: Poor at enterprise volume.

4. Middleware/iPaaS (Zapier, Make)

Use pre-built connectors to move records between platforms trigger-by-trigger or in batches.

• When to use: Ongoing sync of small data volumes post-migration. Not for historical migration.
• Pros: No-code setup. Works for incremental sync after the main migration.
• Cons: Extremely slow for bulk migration. Per-task pricing gets expensive at scale. No support for Ticket Import API, so no historical timestamps.
• Scalability: Not viable for migration; only for narrow post-cutover delta sync.

5. Managed Migration Service

A dedicated migration team builds and runs the ETL pipeline, handles edge cases, manages rate limiting, and validates the output.

• When to use: Enterprise datasets, complex Klass structures, zero-downtime requirements, or when engineering bandwidth is allocated elsewhere.
• Pros: Fastest turnaround. Full handling of relationships, KObjects, attachments. Built-in validation and rollback.
• Cons: Higher upfront cost than self-serve tools.
• Scalability: Enterprise-grade.

Approach Comparison

Decision guide:

• <10K records, no custom Klasses: Self-serve tool or CSV
• 100K+ records, custom Klasses: Managed service or dedicated dev team
• Historical migration + ongoing sync: Managed service for historical data, then Zapier/Make for incremental sync
• Low engineering bandwidth: Managed service

Pre-Migration Planning

Data Audit

Before extracting anything, audit your Kustomer instance:

• Total Companies and their custom attributes
• Total Customers (and count of duplicate emails)
• Total Conversations and Messages (with date range distribution)
• Active custom Klasses and KObject counts per Klass
• Tags in use (active vs. orphaned)
• Teams and agent assignments
• Attachment volume (count and total size)
• Conversations older than 2 years (these require Kustomer's Archive Search endpoint)
• Business rules, workflows, and shortcuts — these don't migrate programmatically and need manual rebuild

Decide what should not move. Historical noise is expensive to carry. For detailed scoping guidelines, see the Help Desk Data Migration Playbook.

Migration Strategy

If agents must keep working during the migration, plan an incremental cutover with a parallel validation window. See Zero-Downtime Help Desk Data Migration for the operating model.

Always run a test migration on a Zendesk sandbox instance before touching production. Zendesk offers sandbox environments on Professional plans and above.

API Rate Limits and Extraction Constraints

Rate limits are the single biggest bottleneck in any Kustomer-to-Zendesk migration. Both platforms enforce strict limits that directly control migration speed.

Kustomer API Limits (Extraction Side)

Kustomer's API rate limits are tiered by plan:

These limits are org-wide — every API key in your organization shares the same bucket. If your support team is actively using Kustomer during extraction, their actions consume the same rate limit pool. (help.kustomer.com)

Pagination adds friction. Kustomer's standard Search API has a hard cap of 100 pages per query and only returns records updated within the past 2 years. The search endpoint caps at 10,000 records with a maximum of 500 records per page. For older conversations, you must use the Archive Search endpoint (/v1/customers/archive/search). Missing this means silently losing historical data.

To extract a full dataset larger than 10,000 records, segment queries by createdAt or updatedAt date ranges and iterate through each segment.

Zendesk API Limits (Ingestion Side)

Zendesk's Support API rate limits are plan-dependent:

The High Volume API add-on increases the limit to 2,500 req/min on qualifying plans (Growth and above, minimum 10 agent seats). It replaces the existing limit — it does not add to it.

Endpoint-specific limits matter too:

• Ticket Import: Uses the account-wide rate limit (no separate cap)
• Incremental Export: 10 req/min (30 with High Volume add-on)
• Update Ticket: 100 req/min per account

For a migration, the math is straightforward. On a Professional plan at 400 req/min, importing a ticket with all comments bundled requires one request per ticket plus one request per attachment upload. At 400 req/min with zero attachment overhead, that's a theoretical maximum of ~24,000 tickets per hour. In practice, expect 40–60% of that throughput due to retries, payload size variation, and 429 responses.

Your migration pipeline must include a dynamic throttling mechanism that reads the X-RateLimit-Remaining and Retry-After headers from both APIs. Use a message broker (like RabbitMQ or AWS SQS) to queue records and control exact throughput.

Step-by-Step Migration Architecture

The data flow follows a standard Extract → Transform → Load pattern, with platform-specific engineering at each stage.

Step 1: Extract from Kustomer

Extract in dependency order:

1. Companies → GET /v1/companies
2. Customers → GET /v1/customers (includes relationships.org)
3. Users (Agents) → GET /v1/users
4. Teams → GET /v1/teams
5. Conversations → GET /v1/customers/{id}/conversations (per customer)
6. Messages → GET /v1/conversations/{id}/messages (per conversation)
7. KObjects → GET /v1/customers/{id}/kobjects (per customer, per Klass)
8. Attachments → Download from URLs embedded in message bodies

For bulk extraction, use POST /v1/customers/search with queryContext: 'conversation' and conversation_-prefixed sort/filter fields. For data older than 2 years, switch to POST /v1/customers/archive/search and page forward using conversation_updated_at. If you filter by tags, use tag IDs, not display names. (help.kustomer.com)

POST /v1/customers/search
Authorization: Bearer <KUSTOMER_KEY>
 
{
  "and": [
    {"conversation_updated_at": {"gte": "2024-01-01T00:00:00.000Z"}}
  ],
  "queryContext": "conversation",
  "sort": [{"conversation_updated_at": "asc"}],
  "timeZone": "GMT"
}

Kustomer uses cursor-based pagination with page [size] (max 100) and page [after] parameters. Always handle the links.next cursor from each response.

Store raw JSON payloads in a staging database (e.g., PostgreSQL) so you don't have to re-query Kustomer if your pipeline fails mid-run.

Step 2: Transform

Key transformations:

• Status mapping: Kustomer's open, snoozed, done → Zendesk's new, open, pending, solved, closed
• Multi-email flattening: Pick the primary email, create additional identities via Zendesk's User Identities API
• Assignee consolidation: Multiple Kustomer assignees → single Zendesk assignee + tags for others
• Message → Comment conversion: Set author_id based on message direction, map created_at timestamps, set public based on note vs. message
• Inline image URL rewriting: Download from Kustomer CDN, re-upload to Zendesk via Uploads API, replace URLs in HTML body
• KObject → Custom Object record: Schema translation, field type conversion, UUID remapping

Preserve comment order by source timestamp, not extraction order. Decide whether each Klass becomes a custom object, a custom field, or an archived reference based on Zendesk's plan limits.

Step 3: Load into Zendesk

Load in dependency order:

1. Organizations → POST /api/v2/organizations/create_many
2. End Users → POST /api/v2/users/create_many
3. Agents → Create or match agents before ticket import
4. Group Memberships → POST /api/v2/group_memberships
5. Tickets + Comments → POST /api/v2/imports/tickets (preserves timestamps, skips triggers)
6. Custom Object schemas → POST /api/v2/custom_objects
7. Custom Object records → POST /api/v2/custom_objects/{key}/records

The Ticket Import API is essential — it's the only way to set created_at on comments and include multiple comments in a single ticket creation request. It skips Zendesk triggers and automations, which is what you want for historical data. For closed historical tickets, use the archive_immediately=true parameter. (developer.zendesk.com)

For batch imports, use /api/v2/imports/tickets/create_many with up to 100 tickets per request.

Python Script Structure

import requests
import time
 
KUSTOMER_API = "https://api.kustomerapp.com/v1"
ZENDESK_API = "https://yourco.zendesk.com/api/v2"
 
def extract_conversations(customer_id, headers):
    url = f"{KUSTOMER_API}/customers/{customer_id}/conversations"
    conversations = []
    while url:
        resp = requests.get(url, headers=headers)
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get('Retry-After', 60)))
            continue
        data = resp.json()
        conversations.extend(data.get('data', []))
        url = data.get('links', {}).get('next')
    return conversations
 
def transform_to_zendesk_ticket(conversation, messages, user_map):
    comments = []
    for msg in sorted(messages, key=lambda m: m['attributes']['createdAt']):
        comments.append({
            "author_id": user_map.get(
                msg['attributes'].get('sentBy', {}).get('id')
            ),
            "created_at": msg['attributes']['createdAt'],
            "html_body": msg['attributes'].get('preview', ''),
            "public": msg['attributes'].get('direction') != 'internal'
        })
    return {
        "ticket": {
            "subject": conversation['attributes'].get(
                'name', 'Imported conversation'
            ),
            "comments": comments,
            "requester_id": user_map.get(
                conversation['relationships']['customer']['data']['id']
            ),
            "tags": conversation['attributes'].get('tags', [])
                + ["kustomer-import"],
            "created_at": conversation['attributes']['createdAt'],
            "status": map_status(
                conversation['attributes'].get('status')
            )
        }
    }
 
def import_ticket(ticket_payload, zendesk_auth):
    resp = requests.post(
        f"{ZENDESK_API}/imports/tickets",
        json=ticket_payload,
        auth=zendesk_auth,
        headers={"Content-Type": "application/json"}
    )
    if resp.status_code == 429:
        wait = int(resp.headers.get('Retry-After', 60))
        time.sleep(wait)
        return import_ticket(ticket_payload, zendesk_auth)
    return resp.json()

After the main load, run a delta pass for records created or updated in Kustomer during the migration window. Keep batch IDs, source IDs, target IDs, payload hashes, retry counts, and a dead-letter queue for records that fail after backoff.

Edge Cases That Break Migrations

Standard fields map cleanly. The following edge cases are where migrations actually fail.

Attachments and Inline Images

Kustomer stores attachments on its own CDN. These URLs become inaccessible after account cancellation. You must:

1. Download every attachment during extraction to temporary storage
2. Upload to Zendesk via POST /api/v2/uploads to receive an upload token
3. Include tokens in the uploads array within each comment
4. For inline images, parse the HTML body of the Kustomer message, replace each src URL with the new Zendesk attachment URL, and push the transformed HTML

Each attachment upload is a separate API request, which compounds rate limit pressure. Zendesk ticket attachments max out at 50 MB per file. (support.zendesk.com)

Duplicate Records

Kustomer allows multiple customer records with the same email. Zendesk requires unique emails per end user. Your transform layer needs deduplication logic — typically, merge by email and concatenate phone numbers and external IDs.

Use Zendesk's Idempotency-Key header on ticket creation requests to prevent duplicate tickets during retries.

Multi-Level Relationship Chains

A complete migration must preserve: Organization → End User → Ticket → Comment → Attachment. Each level depends on IDs from the previous level. Build an ID mapping table (Kustomer ID → Zendesk ID) and process in strict dependency order. Group memberships are a separate resource from user creation — don't skip them. (support.zendesk.com)

Conversations Older Than 2 Years

Kustomer's standard Search API only returns records updated within the past 2 years. For older conversations, you must use the Archive Search endpoint (/v1/customers/archive/search). Missing this is one of the most common and costly mistakes in Kustomer extractions — it silently drops historical data with no error or warning.

Very Long Conversations

Zendesk tickets have a hard cap of 5,000 comments, and each comment is limited to 65,535 characters. (developer.zendesk.com)

Because Kustomer allows endless conversations, a single Kustomer Conversation can contain thousands of Messages. Zendesk's UI also degrades well before the 5,000 limit — tickets with hundreds of comments become unwieldy. Implement logic in your pipeline to split excessively long conversations into discrete Zendesk tickets, linked via custom fields or tags.

Limitations and Constraints

Be honest with stakeholders about what doesn't survive the migration:

• Timeline view. Kustomer's unified customer timeline — all conversations, KObjects, and events in one stream — has no direct equivalent in Zendesk. Zendesk shows tickets per user, not a unified timeline. You can preserve history, but not the exact reading experience. (help.kustomer.com)
• Business rules and workflows. Kustomer's workflow automations do not export and cannot be programmatically migrated. Triggers, automations, and macros must be rebuilt manually in Zendesk. For guidance, see How to Migrate Automations, Macros, and Workflows.
• SLA metrics. Zendesk explicitly warns that metrics and SLAs are not accurate for imported tickets. Tag them and exclude them from historical reports.
• Multi-assignee history. Zendesk supports one assignee per ticket. Kustomer's multi-assignee history can only be approximated via tags or custom fields.

Validation and Post-Migration Tasks

Validation Process

1. Record count comparison: Total organizations, users, tickets, and comments in Zendesk must match Kustomer source counts.
2. Field-level spot checks: Sample 50–100 records across old and new date ranges, open and closed states. Verify names, emails, custom field values, timestamps, and public/private state.
3. Conversation thread integrity: Open 20+ migrated tickets and verify the comment sequence matches the original Kustomer timeline — correct order, correct authors, correct timestamps.
4. Attachment verification: Confirm embedded images render and file attachments are downloadable.
5. Custom object records: Verify Klass data appears correctly in Zendesk Custom Object records with proper lookup relationships.

Validation should be boring and numeric. Don't settle for row counts alone — check the ugliest records in the dataset. For a detailed post-migration QA process, see Post-Migration QA: 20 Tests to Run.

Post-Migration Tasks

Migrating the data is half the job. After go-live:

• Rebuild triggers and automations in Zendesk to replicate Kustomer business rules
• Configure macros based on Kustomer shortcuts and snippets
• Set up routing — Kustomer queues → Zendesk routing rules and views
• Train agents on Zendesk's ticket model vs. Kustomer's timeline model
• Monitor for data inconsistencies for the first 2 weeks — spot-check daily
• Disable or cancel Kustomer only after confirming all attachments and data are verified in Zendesk

For rollback safety, never hand-edit bad batches in production. Tag imported records, preserve external IDs, and delete/reload by batch.

Why ClonePartner for Kustomer-to-Zendesk Migrations

We built our migration engine for helpdesk-to-helpdesk moves where data model translation is the hard problem. For Kustomer-to-Zendesk specifically:

• Klass-to-Custom Object mapping is handled natively — including schema analysis, field type conversion, and record creation via the new Custom Objects API.
• Dynamic rate throttling adjusts request rates in real time against both Kustomer's plan-based limits and Zendesk's tier-based limits, preventing 429 errors without manual tuning.
• Full conversation fidelity — every message becomes a properly timestamped, properly attributed comment. Thread order is preserved. Inline images are re-hosted.
• Large dataset reliability — we routinely handle 500K+ record migrations without the timeout failures common in self-serve tools.
• Zero downtime — your support team keeps working in Kustomer during extraction and switches to Zendesk after validation. We handle the delta sync for records created during the migration window.

In-house migrations silently kill product velocity. When engineers spend cycles deciphering undocumented API behaviors and writing retry logic for edge cases, core product development stalls.

The Bottom Line

Migrating from Kustomer to Zendesk is a data modeling and API management exercise. Success requires translating a continuous customer timeline into discrete tickets, rebuilding complex relational objects, and strictly managing rate limits across both platforms.

Whether you build an internal ETL pipeline or partner with a migration service, prioritize data fidelity over speed. Audit your custom Klasses early. Build resilient retry logic for attachments. Use Zendesk's Import API to preserve historical timestamps. And plan for conversations older than two years — Kustomer's Search API won't surface them unless you explicitly use Archive Search.