Zammad to Kayako Migration Playbook

TL;DR

Zammad to Kayako migration requires API-to-API scripting with no native path. Route articles to cases/replies/notes, preserve timestamps via bulk import, and validate aggressively.

There is no native migration path, built-in connector, or vendor-provided import wizard from Zammad to Kayako—while Zammad offers a migrator for importing from Kayako, no reverse path exists. The fundamental data model difference centers on Zammad's article-based ticket messaging versus Kayako's conversation-centric case model, with internal notes routed to entirely separate API endpoints in Kayako. A reliable migration requires building or commissioning an API-to-API pipeline that extracts via Zammad's REST API and loads through Kayako's Cases API, with custom transform logic to handle field mapping, internal note routing, attachment transfer, and timestamp preservation.

Read this first

Pair-specific gotchas that catch teams out. Each one has cost somebody a weekend.

API Versioning Note

This guide is based on Zammad 6.x REST API and Kayako API v1 as of mid-2026. Zammad's API can change between major self-hosted versions — verify endpoint behavior against your installed version before scripting. Zammad Cloud instances may have different API rate limits or disabled endpoints compared to self-hosted installations — confirm access to all extraction endpoints before beginning. Several Kayako API reference pages still show a last-updated date of January 2017, so validate behavior in a sandbox before production. (developer.kayako.com)

Internal Notes Routing

Zammad's internal notes are articles on the ticket with internal: true. Kayako separates notes from case messages entirely — they live at a different API endpoint (/api/v1/cases/{id}/notes). Your migration script must detect internal articles and route them to Kayako's notes API, not the replies endpoint. Getting this wrong means internal agent notes become visible to customers. This is the single most common data exposure mistake in helpdesk migrations.

If your support team uses Zammad as a pseudo-CRM, split the project in two

Migrate support history into Kayako. Keep sales and marketing objects in the CRM, and carry only reference IDs or read-only context that agents need. Kayako documents cases, forms, types, users, and organizations — it is not a pipeline system.

Zammad Search Limit

Zammad's search endpoint (/api/v1/tickets/search) has a hard limit of 10,000 results regardless of pagination. If you have more than 10K tickets, do not use the search endpoint for extraction. Paginate through /api/v1/tickets using page and per_page parameters. If the paginated list endpoint also truncates at high page numbers, iterate by ticket ID ranges (e.g., GET /api/v1/tickets?page=1&per_page=100 and track the highest ID returned).

Timestamp Override

If you do not explicitly pass the historical created_at timestamp when creating a Kayako Case, Kayako will stamp it with the current server time. The bulk cases endpoint explicitly documents support for historical created_at and updated_at on both cases and nested posts. For single-case creates via POST /api/v1/cases.json, verify in your Kayako sandbox that created_at overrides are accepted — some Kayako plans or API versions may ignore this field on single creates. (developer.kayako.com)

Kayako's PUT-only update model

Kayako does not support PATCH. Any update via PUT must include all required fields, or omitted fields may silently revert to defaults. For multi-select custom fields, Kayako's documentation explicitly warns that omitted values are removed on update — never update field values without sending the full intended set. This is especially dangerous during post-migration corrections. (developer.kayako.com)

Field mapping reference

The field-by-field mapping for each object. Use this as the starting point for your mapping spec.

Zammad Kayako 15 fields

Zammad field	Kayako field	Notes
ticket.number	legacy_id	Store Zammad ticket number as Kayako's legacy_id for traceability
title	subject	Direct map
state_id	status_id	Map: new→New, open→Open, pending reminder/pending close→Pending, closed→Closed. Status IDs are instance-specific — query GET /api/v1/cases/statuses to get your Kayako instance's actual IDs. Create custom statuses in Kayako first if needed.
priority_id	priority_id	Query GET /api/v1/cases/priorities to get Kayako's priority IDs. Verify label alignment between platforms.
group_id	assigned_team_id	Create teams first, build lookup map
owner_id	assigned_agent_id	Match by email; only if agent exists in Kayako
customer_id	requester_id	Match or create by email
organization_id	organization_id	Load orgs first, build lookup map
tags	tags	Direct map; comma-separated on Kayako side
created_at	created_at	Must be explicitly passed. Bulk import endpoint documents historical timestamp support. Without explicit passing, Kayako stamps with current server time.
updated_at	updated_at	Must be explicitly passed
article.body	posts [].contents or reply contents	Sanitize HTML encoding; extract inline base64 images
article.internal	Route to Notes API	true → POST to /api/v1/cases/{id}/notes, not replies
article.attachments	attachment_file_ids or multipart upload	Upload files first via Files API for bulk import
Custom ticket/user/org fields	field_values [...]	Pre-create fields and map types carefully. Verify option values match exactly for select/dropdown fields.

Data Endpoint 8 fields

Zammad field	Kayako field	Notes
Tickets	GET /api/v1/tickets?page=X&per_page=Y&expand=true	Paginate with page and per_page. Max per_page is 500.
Articles	GET /api/v1/ticket_articles/by_ticket/{ticket_id}	Returns all articles for a ticket
Attachments	GET /api/v1/ticket_attachment/{ticket_id}/{article_id}/{attachment_id}	Returns binary content
Users	GET /api/v1/users?page=X&per_page=Y&expand=true	Includes role, organization, custom fields
Organizations	GET /api/v1/organizations?page=X&per_page=Y
Groups	GET /api/v1/groups	Maps to Kayako Teams
Tags	GET /api/v1/tags?object=Ticket&o_id={ticket_id}	Per-ticket tags
Custom attributes	GET /api/v1/object_manager_attributes	Schema definitions for custom fields

Load in Kayako 8 fields

Zammad field	Kayako field	Notes
Organizations	POST /api/v1/organizations	Create before users. Response: {"data": {"id": ...}}
Users	POST /api/v1/users	Create customer/agent users. Response includes id in data object.
Cases	POST /api/v1/cases.json	Creates a case with initial message
Bulk cases	POST /api/v1/bulk/cases.json	Batch creation — up to 200 cases per request. Supports legacy_id and historical timestamps.
Replies	POST /api/v1/cases/{id}/replies	Add subsequent public messages
Notes	POST /api/v1/cases/{id}/notes	Internal notes (separate from messages)
File uploads	POST /api/v1/files	Upload first, then reference attachment_file_ids in case creation
Case deletion	DELETE /api/v1/cases/{id}	For rollback — no bulk delete endpoint; must iterate

Risk matrix

Per-object risk for this pair. Plan extra validation around anything marked high.

Object	Risk	Notes
Tickets/Cases	medium	One-to-one mapping is structurally straightforward, but preserving original timestamps and status values requires explicit field mapping and use of Kayako's `created_at` override.
Articles/Messages	high	Zammad's article model must be split between Kayako's posts/replies endpoint and its separate notes endpoint based on the internal flag, making misrouting a significant data exposure risk.
Internal Notes	high	Failure to detect Zammad's `internal: true` articles and route them to Kayako's dedicated notes API is the single most common data exposure mistake in helpdesk migrations.
Contacts/Users	low	Customer and agent users can be matched by email address across both platforms, though role mappings (agent vs. admin vs. collaborator) require manual verification.
Organizations	low	Both platforms support organization objects linked to users, and these must be loaded before users and cases to preserve relational integrity.
Custom Fields	high	Zammad supports custom object attributes on groups and uses exotic field types that have no direct Kayako equivalent, requiring type conversion, flattening, or data loss.
Attachments	medium	Attachments must be individually extracted from Zammad articles and re-uploaded to Kayako, with volume directly impacting migration duration and API rate limit consumption.
Tags	low	Both platforms support per-ticket/per-case tags with a direct mapping, making this a straightforward transfer with minimal transformation.
Groups/Teams	medium	Zammad's nested group hierarchies must be flattened into Kayako's flat team structure, potentially losing organizational granularity and requiring routing rule adjustments.
Knowledge Base	medium	Zammad's multilingual knowledge base with categories and answers must be restructured into Kayako's Help Center sections and articles, treated as a separate migration scope.

The hard parts

What makes this specific migration difficult, beyond the mechanics.

Internal Notes Data Exposure

Zammad stores internal notes as ticket articles with an `internal: true` flag, but Kayako separates notes onto a distinct API endpoint, so misrouting them to the replies endpoint exposes private agent communications to customers.

Nested Group Flattening

Zammad supports nested group hierarchies for ticket routing, while Kayako uses a flat team structure, requiring all nested groups to be flattened and remapped before loading.

Custom Field Type Mismatches

Zammad allows custom object attributes on tickets, users, organizations, and groups, but Kayako only supports custom fields on cases, users, and organizations, meaning group-level and exotic-type fields must be flattened or dropped.

API Rate Limit Management

Both Zammad and Kayako impose API rate limits that require implementing pagination, exponential backoff, batch checkpointing, and dead-letter queues to avoid failed or incomplete data transfers at scale.

Attachment and Inline Image Transfer

Attachments must be individually downloaded from Zammad's article API and re-uploaded to Kayako's case posts, with inline images requiring HTML reference rewriting to maintain message fidelity.

Automation and Workflow Rebuild

Zammad triggers, schedulers, macros, and SLAs cannot be migrated programmatically and must be manually rebuilt in Kayako's automation and journey builder interfaces.

What breaks

Known failure modes. Have a recovery plan for each before you cut over.

Duplicate users

Zammad allows users without email addresses in some configurations (e.g., Twitter integrations, phone-only contacts). Kayako enforces strict email uniqueness. Generate deterministic placeholder emails (e.g., zammad-user-{id}@placeholder.local) for these profiles. For users with emails, deduplicate on email (case-insensitive), not display name. (admin-docs.zammad.org)

Internal notes becoming public

If your script posts internal articles to Kayako's replies endpoint instead of the notes endpoint, those notes become visible to customers. This is the most common data exposure mistake in helpdesk migrations. Mitigate by checking both article.internal == true and article.type == "note" — belt and suspenders.

Inline images

Zammad users frequently paste images directly into the editor. These are stored as base64 strings in the HTML body (<img src="data:image/png;base64,...">) or as referenced attachments. Your script must: (a) parse the HTML with a library like BeautifulSoup, (b) extract base64 content from data: URIs, (c) upload each image to Kayako via the Files API, (d) rewrite the <img> tag's src to reference the uploaded file URL.

Zammad article types vary

Article types include email, note, phone, web, chat, twitter status, twitter dm, facebook feed post, and others depending on installed channels and add-ons. Do not assume every article is a customer-visible email — check the type and internal flag on every article. (docs.zammad.org)

Kayako archived cases

Closed Kayako cases older than 30 days are omitted from the default GET /api/v1/cases response unless you add archived=1 as a query parameter. This distorts post-cutover audits done weeks later — your validation script must include this parameter. (help.kayako.com)

Attachment size limits

Kayako plan-dependent file size limits may reject large attachments (common limits: 20MB–50MB per file depending on plan). Log any that exceed the limit for manual handling rather than letting the entire case creation fail.

Reassignment audit trails

If a Zammad ticket was reassigned multiple times, the historical audit log entries are stored separately from articles. Focus on migrating the messages and current assignment, not the metadata audit trail — Kayako does not have an equivalent audit log import endpoint.

Enum field updates

Kayako warns that omitted multi-select values are removed on PUT updates. Never update field values without sending the full intended set. (developer.kayako.com)

Missing file uploads

Failed attachment uploads create valid cases with broken history links. Implement retry logic (at least 3 retries with exponential backoff) for every file upload, and verify attachment counts per case after migration against expected counts from Zammad. (developer.kayako.com)

HTML rendering differences

Zammad's rich text editor and Kayako's editor handle whitespace, line breaks, and CSS differently. Common issues: <br> vs <p> tag handling, CSS classes stripped by Kayako's sanitizer, table layouts collapsing. Visual QA on 20–30 tickets before full migration is essential.

Tools used in this playbook

All free, all run entirely in your browser — nothing is uploaded.

Helpdesk Evaluator Sanity-check that Kayako is the right target before you commit COI & ROI Calculator Build the 36-month business case you will need for sign-off Helpdesk Migration Planner Turn ticket volume into a dated Zammad → Kayako timeline Data Profiler Get real record counts instead of estimating from memory PII & Compliance Scanner Find regulated fields before they land in a new system CSV Validator Catch broken headers and ragged rows in the raw export Data Cleaner Strip empty rows, stray whitespace and dead columns PII Masker Generate a safe copy for sandbox and vendor testing Regex Tester with Migration Patterns Prototype the extraction patterns before scripting them Schema Mapper Opens pre-loaded with the Zammad → Kayako field pair Data Format Converter Reshape the export into the format Kayako's importer expects CSV to JSON Converter Turn flat exports into the JSON the API expects JSON to CSV Converter Flatten nested API responses into a reviewable sheet XML to JSON Converter Convert legacy XML payloads for a JSON-first importer CSV to SQL Converter Load the export into a staging table you can query Migration Validation Tool Diff the pilot batch against source before scaling up JWT Decoder Inspect the token when the API rejects your calls Base64 Decoder Decode attachment payloads to confirm they survived transit Cron Expression Builder Schedule the delta syncs that run through the freeze

FAQ

Is there a native migration tool from Zammad to Kayako?

No. Zammad has a built-in migrator for importing FROM Kayako into Zammad, but there is no reverse path. Zammad-to-Kayako requires API-based extraction and loading via custom scripts or a managed migration service.

Can I migrate Zammad tickets to Kayako using CSV?

Only for small, flat datasets. Zammad's reporting download is limited to 6,000 entries and does not export individual articles, internal notes, or attachments. Kayako has no native bulk CSV import for cases. Full thread history and timestamps require API-based migration.

How do I migrate Zammad internal notes to Kayako?

Zammad stores internal notes as articles with 'internal: true'. In Kayako, notes are a separate resource — you must POST them to the /api/v1/cases/{id}/notes endpoint, not the messages/replies endpoint. Getting this wrong exposes internal notes to customers.

How long does a Zammad to Kayako migration take?

For a DIY approach: 3–5 days for under 5K tickets with no custom fields, 1–3 weeks for 5K–50K tickets with custom fields and attachments. A managed migration service typically completes in 3–5 business days regardless of complexity.

Does Kayako preserve historical timestamps during import?

The bulk cases endpoint (POST /api/v1/bulk/cases.json) explicitly supports historical created_at and updated_at on both cases and posts. For single-case creates, verify that your Kayako plan accepts created_at overrides — if not, all imported cases will be stamped with the current date.

Zammad to Kayako: The Complete Migration Playbook