---
title: "How to Migrate from Zendesk to HappyFox: Complete Technical Guide"
slug: how-to-migrate-from-zendesk-to-happyfox-complete-technical-guide
date: 2026-07-06
author: Raaj
categories: [Migration Guide, HappyFox, Zendesk]
excerpt: "Step-by-step guide to migrating Zendesk to HappyFox. Covers API rate limits, object mapping, custom field transformation, attachment handling, and cutover."
tldr: "A Zendesk to HappyFox migration takes 3–10 days for most teams. Biggest risks: Zendesk's 10 req/min limit, expiring attachment URLs, and HappyFox's choice-ID custom field format."
canonical: https://clonepartner.com/blog/how-to-migrate-from-zendesk-to-happyfox-complete-technical-guide/
---

# How to Migrate from Zendesk to HappyFox: Complete Technical Guide


# How to Migrate from Zendesk to HappyFox: Complete Technical Guide

> [!NOTE]
> **Quick Answer:** A Zendesk to HappyFox migration is moderately complex. The hard part is not exporting ticket rows — it is rebuilding comment history, attachments, and custom field mappings between two different help desk models. Zendesk's Incremental Export API caps at 10 requests per minute (30 with the High Volume add-on), attachments must be extracted from individual ticket comments, and HappyFox's custom fields use a `t-cf-{id}` reference pattern with choice IDs instead of Zendesk's flat `{id, value}` format. Realistic timeline: 3–10 days for most teams under 100K tickets, 2–4 weeks for enterprise volumes above 250K tickets. The single biggest risk is losing ticket attachments and inline images during extraction. Zendesk Triggers, Automations, Macros, and Views cannot be migrated programmatically — they must be rebuilt manually in HappyFox.

*Last updated: July 2025. API behaviors described reflect Zendesk API v2 and HappyFox API v1.1 as of this date.*

## What Is a Zendesk to HappyFox Migration?

A **Zendesk to HappyFox migration** is the process of extracting tickets, contacts, organizations, tags, custom fields, and attachments from Zendesk Support and loading them into HappyFox Help Desk while preserving conversation history, data relationships, and file integrity.

### Why Teams Move from Zendesk to HappyFox

The most common driver is cost. As of mid-2025, Zendesk Suite plans start at $55/agent/month (Team) and scale to $115/agent/month (Professional) and $169/agent/month (Enterprise). HappyFox offers per-agent plans starting at $29/agent/month (Mighty) as well as unlimited-agent plans starting at $1,499/month (Enterprise), which eliminates per-seat scaling entirely. The gap widens when Zendesk AI add-ons ($50/agent/month for Advanced AI) compound per seat.

HappyFox includes SLA management on all paid plans. Zendesk gates SLA features behind Professional tier and above. Teams consolidating support, IT, and HR ticketing under one roof find HappyFox's multi-department category architecture a natural fit — each category functions as an independent queue with its own ticket ID prefix, SLA rules, and agent permissions.

### Core Architectural Differences That Make This Non-Trivial

**Custom field structure.** Zendesk stores custom fields as a flat array of `{id, value}` pairs. HappyFox uses internal field references like `t-cf-{id}` for ticket custom fields and `c-cf-{id}` for contact custom fields, with dropdown choices stored as objects containing `id`, `text`, and `dependant_fields` properties. Every custom field value must be transformed during the load phase.

**Organizational hierarchy.** Zendesk uses Organizations to group end-users. HappyFox uses Contact Groups, which have a different association model — contacts can belong to multiple groups, and groups use tagged domains for auto-association. Do not confuse Zendesk Groups (agent routing) with HappyFox Contact Groups (customer-side groupings). ([developer.zendesk.com](https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/))

**Ticket ID format.** Zendesk assigns sequential numeric IDs. HappyFox generates composite IDs using a category prefix plus a number (e.g., `#HFS00000001`). Original Zendesk ticket IDs cannot be preserved natively — store them in a custom text field from day one.

**Status behavior.** HappyFox statuses are customizable, but each status carries a higher-level behavior of either `Pending` or `Completed`. Zendesk's `solved` and `closed` often collapse into one or more Completed-behavior statuses unless you explicitly model a distinction. ([support.happyfox.com](https://support.happyfox.com/kb/article/61-create-and-manage-statuses))

**Workflow rules.** Zendesk Triggers and Automations support arrays of actions (e.g., set priority, add tag, and send notification in a single rule). A HappyFox Smart Rule performs only one action per rule, so one Zendesk rule often becomes 2–5 HappyFox rules. Macros rebuild as Canned Actions. None of these can be migrated via API — they must be rebuilt manually.

## Zendesk to HappyFox Object and Field Mapping

Use the help desk object model, not a CRM model. The mapping below reflects the actual API behavior of both platforms as of HappyFox API v1.1 and Zendesk API v2.

| Zendesk Object | HappyFox Object | Notes / Caveats |
|---|---|---|
| Tickets | Tickets | Status, priority, and category IDs must be mapped by HappyFox internal ID. HappyFox generates a new `id` and `display_id`. |
| Ticket Comments (public, from agent) | Staff Updates (`staff_update`) | Separate endpoint from private notes. Suppress customer notifications during migration. |
| Ticket Comments (public, from requester) | Contact Replies (`user_reply`) | Preserves end-user conversation chronology. |
| Internal Notes | Private Notes (`staff_pvtnote`) | Separate endpoint from public replies. |
| Users (end-users) | Contacts | Email is the unique identifier. Phone fields differ structurally. |
| Users (agents) | Staff | Role and category permissions must be configured manually. |
| Organizations | Contact Groups | Domain-tagged; many-to-many association vs. Zendesk's one-to-one. |
| Groups | Categories + Smart Rules | Agent-routing object, not a customer grouping. HappyFox Categories also control ticket ID prefixes and SLAs. |
| Tags | Tags | Direct migration; tag management permissions may differ. |
| Custom Fields (ticket) | Ticket Custom Fields (`t-cf-{id}`) | Dropdown/multi-select values must use HappyFox choice IDs, not display text. |
| Custom Fields (user) | Contact Custom Fields (`c-cf-{id}`) | Same ID-based reference pattern. |
| Attachments | Attachments | Must use multipart/form-data POST; inline images need a separate upload endpoint. |
| Triggers / Automations | Smart Rules | No automated migration path. One Zendesk rule may become multiple Smart Rules. |
| Macros | Canned Actions | Manual recreation required. |
| Views | Ticket Queues / Filters | Manual recreation required. |
| SLA Policies | SLA Configurations | Available on all HappyFox plans; manual setup required. |
| Satisfaction Ratings | Custom Field (text/numeric) | Stored as data but will not drive HappyFox's native survey system. |
| Side Conversations | ❌ No equivalent | Must be flattened into private notes or lost. |
| Webhooks / Targets | ❌ Manual rebuild | See integration migration section below. |

### Field-Level Transformations

Zendesk sends custom fields as:
```json
{"custom_fields": [{"id": 360000123, "value": "premium"}]}
```

HappyFox expects:
```json
{"t-cf-5": 12}
```
Where `5` is the HappyFox custom field ID and `12` is the **choice ID**, not the display text. For dropdown and multi-select fields, pre-fetch the choice list from `GET /api/1.1/json/ticket_custom_fields/` and build a lookup table mapping Zendesk text values to HappyFox choice IDs. A name match is not enough — if a Zendesk dropdown value is "Tier 1" but the corresponding HappyFox choice ID is `42`, you must send `42`. Sending the text string returns a 400 error. ([developer.zendesk.com](https://developer.zendesk.com/api-reference/ticketing/tickets/tickets/))

### What Has No Clean Equivalent in HappyFox

**Side Conversations** in Zendesk (child tickets or lateral threads) have no equivalent in HappyFox. The standard approach is to append side conversation content as private notes on the parent ticket, prefixed with metadata indicating the original side conversation participants and timestamps.

**Satisfaction ratings** (CSAT surveys) from Zendesk can be stored in a custom field but will not drive HappyFox's native survey system. Export the full CSAT dataset from Zendesk's `GET /api/v2/satisfaction_ratings` endpoint and store it in a reporting database if historical CSAT trends matter.

**Ticket metrics** like first-reply time and full-resolution time are read-only audit data in Zendesk (`GET /api/v2/ticket_metrics`) and have no import target in HappyFox. Archive them separately if needed for historical reporting.

## How to Extract Data from Zendesk: The 10 Req/Min API Limit

Zendesk's Incremental Export API (`GET /api/v2/incremental/tickets/cursor`) is the only viable method for bulk ticket extraction. The rate limit is 10 requests per minute globally — shared across all export jobs on your account. With the High Volume API add-on (available on Growth plans and above, minimum 10 agent seats), this increases to 30 requests per minute. ([developer.zendesk.com](https://developer.zendesk.com/api-reference/ticketing/ticket-management/incremental_exports/))

Each incremental export page returns up to 1,000 tickets. At 10 requests per minute, that is a theoretical maximum of 10,000 tickets per minute for ticket shells — but you still need comments and attachments.

### Attachment Extraction: The Hidden Bottleneck

Zendesk ticket exports do not include attachment binaries. You must call `GET /api/v2/tickets/{ticket_id}/comments` for each ticket, iterate through the `attachments` array in each comment, and download files from the `content_url`. These URLs are authenticated and short-lived — download them immediately after fetching comments. If you queue URLs for later processing, they will expire and return a `403 Forbidden` error. Store downloaded files in a secure temporary location (e.g., an encrypted S3 bucket with server-side encryption and a lifecycle policy to auto-delete after 30 days). ([developer.zendesk.com](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/))

For a Zendesk instance with 50,000 tickets averaging 5 comments per ticket, that is at least 50,000 additional API calls for comments alone. Comments are paginated at 100 per page, and a single ticket can have up to 5,000 comments — a small number of long-lived tickets can dominate extraction time.

**Attachment size limits.** Zendesk allows up to 50 MB per individual attachment (documented in [Zendesk's attachment API reference](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket-attachments/)). HappyFox's per-attachment limits vary by plan — verify your plan's limit via HappyFox support before migration, as exceeding it causes silent upload failures.

### Deduplication

Zendesk's time-based incremental exports can return duplicate items when multiple records share the same `updated_at` timestamp. Cursor-based pagination (`/api/v2/incremental/tickets/cursor`) avoids most of these issues and is the recommended approach. If you fall back to time-based exports, deduplicate by `id` + `updated_at`. The incremental export also excludes items changed in the minute before the request — account for this gap in your delta sync timing. ([developer.zendesk.com](https://developer.zendesk.com/documentation/api-basics/working-with-data/using-the-incremental-export-api/))

```python
# Zendesk cursor-based incremental export with attachment download
import requests, time, os

ZENDESK_SUBDOMAIN = "yourcompany"
AUTH = ("email@example.com/token", "your_api_key")

url = f"https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/incremental/tickets/cursor"
params = {"start_time": 1609459200}  # Unix epoch — adjust to your cutoff
all_tickets = []

while True:
    resp = requests.get(url, params=params, auth=AUTH)
    if resp.status_code == 429:
        retry_after = int(resp.headers.get("Retry-After", 60))
        time.sleep(retry_after)
        continue
    resp.raise_for_status()
    data = resp.json()
    all_tickets.extend(data["tickets"])
    if data.get("end_of_stream"):
        break
    params = {"cursor": data["after_cursor"]}
    time.sleep(6)  # Respect 10 req/min

# Fetch comments and download attachments immediately
for ticket in all_tickets:
    comments_url = f"https://{ZENDESK_SUBDOMAIN}.zendesk.com/api/v2/tickets/{ticket['id']}/comments"
    comments_resp = requests.get(comments_url, auth=AUTH)
    if comments_resp.status_code == 429:
        time.sleep(int(comments_resp.headers.get("Retry-After", 60)))
        comments_resp = requests.get(comments_url, auth=AUTH)
    for comment in comments_resp.json().get("comments", []):
        for attachment in comment.get("attachments", []):
            # Download immediately — URLs expire
            file_resp = requests.get(attachment["content_url"], auth=AUTH)
            filepath = f"attachments/{ticket['id']}/{attachment['id']}_{attachment['file_name']}"
            os.makedirs(os.path.dirname(filepath), exist_ok=True)
            with open(filepath, "wb") as f:
                f.write(file_resp.content)
```

For a deeper look at export methods, see our guide on [how to export tickets from Zendesk](https://clonepartner.com/blog/blog/how-to-export-tickets-from-zendesk/).

## How to Load Data into HappyFox: API Rate Limits and Batching

HappyFox's Help Desk API v1.1 enforces rate limits of **500 GET requests per minute** and **300 POST requests per minute**. Exceeding either threshold triggers a `429` error, and the lockout lasts **10 minutes** — not just the current request window. This penalty makes aggressive retry logic dangerous. Batch at roughly 250 POST/min (83% of the limit) and monitor `X-RateLimit-Remaining` response headers. ([support.happyfox.com](https://support.happyfox.com/kb/article/360-api-for-happyfox/))

HappyFox supports bulk ticket creation at `POST /api/1.1/json/tickets/` with up to **100 tickets per request**. Authentication uses Basic HTTP auth with an API key and auth code pair. ([support.happyfox.com](https://support.happyfox.com/kb/article/1039-tickets-endpoint/))

> [!WARNING]
> **HappyFox's create-ticket API only works in public or contact-visible categories.** If your final destination category is private, create the ticket in a temporary public category and move it after creation. This is a documented limitation, not a bug. ([support.happyfox.com](https://support.happyfox.com/kb/article/1413-what-are-public-and-private-categories/))

### Custom Field Transformation on the Load Side

Pre-fetch HappyFox's custom field metadata from `GET /api/1.1/json/ticket_custom_fields/` and build a deterministic lookup table mapping Zendesk text values to HappyFox choice IDs. For contact custom fields, use `GET /api/1.1/json/contact_custom_fields/` and the `c-cf-{id}` pattern with the same ID-based lookup.

```python
# Build HappyFox custom field lookup table
hf_fields = requests.get(
    f"https://{HF_DOMAIN}/api/1.1/json/ticket_custom_fields/",
    auth=(HF_API_KEY, HF_AUTH_CODE)
).json()

choice_lookup = {}  # Maps (hf_field_id, zendesk_text_value) -> hf_choice_id
for field in hf_fields:
    if field["type"] in ("dropdown", "multiselect"):
        for choice in field.get("choices", []):
            choice_lookup[(field["id"], choice["text"].lower().strip())] = choice["id"]
```

> [!WARNING]
> **Contact custom field updates can clear omitted values.** When updating HappyFox contact custom fields via `PUT`, send the complete set of custom field values — the API resets fields you omit from the request payload to their defaults. Always merge existing field values with your updates before submitting. ([support.happyfox.com](https://support.happyfox.com/kb/article/1092-contacts-and-contact-groups-api-endpoints/))

### Comment Replay Architecture

HappyFox uses separate endpoints for different comment types. You cannot bulk-load all comments through a single endpoint. The replay sequence for each ticket:

```python
for ticket in zendesk_tickets:
    hf_ticket = create_ticket_shell(ticket)

    for comment in sorted(ticket.comments, key=lambda c: c.created_at):
        with retry(on=[429, 500, 502, 503, 504], backoff='exponential', max_retries=5):
            if comment.private:
                add_private_note(hf_ticket, comment)
            elif comment.author_role == 'end-user':
                add_contact_reply(hf_ticket, comment)
            else:
                add_staff_reply(hf_ticket, comment, update_customer=False)

        # Critical: do not parallelize writes to the same ticket
        time.sleep(0.2)  # 200ms minimum between per-ticket operations
```

> [!WARNING]
> **Concurrent API calls to the same HappyFox ticket are not supported.** Parallel writes to the same ticket will fail silently or cause data corruption (duplicate comments, lost attachments, out-of-order threading). Serialize all comment replay calls per ticket. You can parallelize across different tickets — use a worker pool where each worker owns a ticket and processes its comments sequentially. ([support.happyfox.com](https://support.happyfox.com/kb/article/1039-tickets-endpoint/))

### Throughput Math

Using the 100-ticket bulk endpoint at 300 POST/min: theoretical max is 30,000 ticket shells per minute. In practice, with attachment uploads (multipart/form-data, one ticket at a time), throughput drops to roughly **2,000–5,000 tickets per hour** for tickets with attachments. Without attachments, expect 10,000–15,000 per hour.

Real projects are bottlenecked by comment replay, not shell creation. Here is the arithmetic:

- 50,000 tickets × 6 non-initial comments per ticket = 300,000 POST requests
- At 250 POST/min (safe threshold) = 1,200 minutes = **20 hours**
- Add ~30% overhead for retries, attachment uploads, and backoff = **~26 hours**
- With attachments on 40% of comments, expect **30–40 hours total**

This is wall-clock time for a single-threaded replay. Parallelizing across tickets (e.g., 4 workers each handling different tickets) can reduce this to 8–10 hours, provided you stay under the aggregate 300 POST/min limit.

## Migration Approaches Compared

There is no official one-click Zendesk-to-HappyFox pipeline. Your options:

| Approach | Best For | Strengths | Limits | Complexity |
|---|---|---|---|---|
| **Native CSV export/import** | Micro-businesses (<5K tickets, no attachments) | Free, no API knowledge needed | Strips attachments, breaks threading, loses timestamps, no inline images | Low |
| **HappyFox onboarding assistance** | Standard scopes with light customization | Platform guidance included in onboarding | Best when customization is light; may not handle complex field mappings | Medium |
| **SaaS migration tool** (e.g., Help Desk Migration) | Mid-size (5K–50K), standard schemas | Fast setup, pre-built connectors | Limited custom field handling; no inline image preservation; can time out on large attachment pulls; typically charges per-record | Medium |
| **Custom ETL scripts** | Teams with in-house dev capacity | Full control over field mapping, retry logic, and validation | 2–6 weeks of engineering time; you own every edge case and rate limit workaround | High |
| **Managed migration service** | Enterprise (>50K), complex schemas, zero-downtime requirement | Custom logic, delta syncs, accountability | Higher external cost ($3K–$20K+ depending on volume and complexity) | Low (for you) |

**Small business pick:** HappyFox's native import or the Help Desk Migration wizard, if you have fewer than 5,000 tickets and no complex custom fields.

**Enterprise pick:** Custom ETL or a managed service. At 50K+ tickets with attachments, the engineering cost of handling rate limits, retries, attachment expiry, and custom field transformation exceeds what a SaaS tool can automate.

For a detailed comparison of tooling options, see [ClonePartner vs Help Desk Migration](https://clonepartner.com/blog/blog/clonepartner-vs-help-desk-migration/).

## Step-by-Step Zendesk to HappyFox Migration Process

### Step 1: Audit and Freeze the Schema

Inventory all Zendesk objects: tickets, comments, attachments, users, organizations, tags, custom fields (including dropdown option values), macros, triggers, automations, views, webhooks, and third-party integrations. Document each custom field's type, required status, and conditional visibility rules.

Freeze changes to custom fields and workflow rules during the migration window. Announce the freeze to admins at least 5 business days before extraction begins.

**Integration inventory.** Document all Zendesk Marketplace apps, webhook targets, Slack/Teams integrations, Salesforce syncs, JIRA connections, and API consumers. Each must be reconnected to HappyFox or replaced with an equivalent. HappyFox supports native integrations with Slack, JIRA, and Salesforce, but configuration differs from Zendesk's — budget 1–3 days for integration reconnection.

### Step 2: Build Mapping and Lookup Tables

Pull Zendesk field metadata via `GET /api/v2/ticket_fields` and `GET /api/v2/user_fields`. Fetch HappyFox categories, statuses, priorities, staff IDs, contact groups, and custom field IDs from the corresponding API endpoints. Build deterministic lookup tables mapping every Zendesk dropdown value to a HappyFox choice ID.

Create a `Legacy Zendesk Ticket ID` custom text field in HappyFox — this one field makes UAT, hypercare, and rollback lookups dramatically faster. Mark it as searchable.

**Status mapping worksheet:**

| Zendesk Status | HappyFox Status | HappyFox Behavior |
|---|---|---|
| New | New | Pending |
| Open | Open | Pending |
| Pending | Waiting on Customer | Pending |
| On-hold | On Hold | Pending |
| Solved | Resolved | Completed |
| Closed | Closed | Completed |

Adjust this mapping to match your HappyFox status configuration. If you need a distinction between Solved (reopenable) and Closed (final), create two Completed-behavior statuses in HappyFox before migration.

### Step 3: Set Up HappyFox Test Environment

If your HappyFox plan includes a sandbox environment, use it for all test loads. If no sandbox is available, create a dedicated test category in your production HappyFox instance with a clear prefix (e.g., `TEST-Migration`). Run a sample migration of 100–500 tickets through the full pipeline before processing the entire dataset. This catches custom field mismatches, attachment upload failures, and comment ordering issues before they affect your production data.

### Step 4: Extract Historical Data from Zendesk

Use the cursor-based Incremental Export API for ticket shells. For each ticket, fetch comments separately and download all attachment files immediately from `content_url` before URLs expire. Store downloaded attachments in a secure temporary location (e.g., an S3 bucket with AES-256 server-side encryption and a 30-day lifecycle deletion policy).

**GDPR and compliance note.** If your tickets contain PII subject to GDPR, CCPA, or HIPAA, ensure your temporary storage location is in a compliant region. Encrypt data at rest and in transit. After migration validation completes, delete all temporary extracts. Document the data handling chain for your compliance team.

Zendesk's incremental export excludes items changed in the 60 seconds before the request — account for this in your delta sync timing by overlapping your extraction windows by at least 2 minutes.

### Step 5: Transform Data for HappyFox's Schema

Convert Zendesk's flat custom field format to HappyFox's `t-cf-{id}` pattern using choice IDs. Map organizations to contact groups. Flatten side conversations into private notes with metadata headers. Map Zendesk statuses to HappyFox status IDs, accounting for the Pending/Completed behavior distinction.

**Inline image rewriting.** Zendesk stores inline images as embedded HTML references hosted on Zendesk's CDN (URLs like `https://yourcompany.zendesk.com/attachments/token/...`). To preserve them in HappyFox:

1. Parse HTML content for `<img src="...zendesk.com...">` tags
2. Download each image from Zendesk
3. Upload to HappyFox's inline attachment endpoint, which returns a temporary URL valid for 5 minutes
4. Rewrite the HTML `src` attribute to the new HappyFox URL
5. Create the ticket/comment immediately — do not batch after upload

If you skip this, all inline images break permanently as soon as you cancel your Zendesk subscription or the CDN URLs expire. ([support.happyfox.com](https://support.happyfox.com/kb/article/1039-tickets-endpoint/))

### Step 6: Load Contacts, Staff, and Contact Groups First

Create or deduplicate HappyFox contacts, staff, and contact groups before loading tickets. If you attempt to load a ticket assigned to a staff ID that does not exist in HappyFox, the API rejects the ticket with a 400 error.

**Load order matters:**
1. Staff accounts (with correct role and category permissions)
2. Contact Groups (with domain associations)
3. Contacts (deduplicated by email, associated with correct groups)
4. Ticket shells
5. Comments and attachments (serialized per ticket)

When updating contact custom fields, send complete merged values to avoid clearing omitted fields.

**Multi-org users.** Zendesk supports multiple organization memberships per user via `GET /api/v2/users/{id}/organization_memberships`. Map each membership to a HappyFox Contact Group association. Since HappyFox contacts can belong to multiple groups natively, this maps cleanly — but you must explicitly create each association rather than relying on auto-assignment. ([developer.zendesk.com](https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/))

### Step 7: Create Ticket Shells, Then Replay History

Load base ticket records using the bulk creation endpoint (up to 100 per request). Store the legacy Zendesk ticket ID in the custom field created in Step 2. If the destination category is private, create in a temporary public category and move the ticket after creation.

Then replay comments in chronological order: requester messages as `user_reply`, agent public messages as `staff_update` (with customer notifications suppressed via the `update_customer` parameter set to `false`), and internal notes as `staff_pvtnote`. Attach files to the correct comment using multipart/form-data. Serialize all writes per ticket — no parallel replay on the same ticket.

**CCs and followers.** Zendesk handles CCs via `collaborator_ids` on the ticket object. Map these to HappyFox's CC fields, ensuring all referenced users exist as HappyFox contacts before ticket creation. Missing CC contacts cause silent data loss, not API errors.

### Step 8: Run Delta Sync, Validate, and Cut Over

After the historical load completes, resume from your last Zendesk cursor to capture any tickets created or updated during the migration window. Load these into HappyFox. Run validation (see below).

**Email routing cutover.** Before cutting over:
1. Configure HappyFox's inbound email settings with your support email addresses
2. If using a forwarding setup: add a forwarding rule in your email provider (Google Workspace, Microsoft 365) to route incoming mail to HappyFox's designated mailbox address
3. If using direct MX routing: update your MX records for the support domain to point to HappyFox's mail servers (provided during onboarding)
4. Update SPF records to include HappyFox's sending IPs (consult HappyFox's email configuration documentation for current values)
5. Configure DKIM signing in HappyFox for your domain
6. Test inbound and outbound email flow with a sample ticket before going live
7. DNS propagation can take up to 48 hours — plan accordingly for MX changes

Then cut agents over and route new email traffic to HappyFox.

## How Long Does a Zendesk to HappyFox Migration Take?

For most teams, the calendar is driven more by mapping, UAT, and workflow rebuild than by raw API throughput.

| Phase | Duration | Dependencies |
|---|---|---|
| Discovery, schema audit, and integration inventory | 1–3 days | Admin access to both Zendesk and HappyFox |
| Field mapping and lookup table construction | 1–2 days | Custom field complexity |
| Test migration (100–500 tickets) | 1 day | HappyFox sandbox or test category |
| Zendesk extraction (full historical) | 1–5 days | Ticket volume, attachment count, API plan tier |
| Transformation and loading | 1–3 days | Custom field complexity, attachment volume |
| Integration reconnection (Slack, JIRA, Salesforce, etc.) | 1–3 days | Number and complexity of integrations |
| Workflow rebuild (Smart Rules, Canned Actions, SLAs) | 1–3 days | Number of Zendesk Triggers/Automations/Macros |
| Validation and UAT | 1–2 days | Stakeholder availability |
| Agent training on HappyFox UI and workflows | 1–2 days | Team size |
| Delta sync, email cutover, and go-live | 4–12 hours | Scheduling a low-traffic window |
| **Total** | **5–14 days (typical)** | **3–5 weeks for 250K+ tickets** |

### Phased vs. Big-Bang Cutover

**Phased (recommended for >50K tickets):** Migrate historical data first while Zendesk stays live. Run a delta sync to catch tickets created or updated during the migration window. Cut over to HappyFox only after validation passes. This approach allows the extraction and loading phases to run over multiple days without pressuring agent workflows.

**Big-bang (viable for <10K tickets):** Export everything over a weekend, validate Monday morning, go live. Risk: if validation fails, you need a rollback plan — keep Zendesk active for at least 14 days post-migration.

For zero-downtime strategies, see [zero-downtime help desk data migration](https://clonepartner.com/blog/blog/zero-downtime-help-desk-data-migration/).

### Risk Register

| Risk | Likelihood | Impact | Mitigation |
|---|---|---|---|
| Zendesk API throttling extends extraction | High | Schedule delay | Use cursor-based pagination; implement exponential backoff; consider High Volume add-on ($) |
| HappyFox 429 triggers 10-minute lockout | Medium | 10-min idle per occurrence | Batch at 250 POST/min (83% of limit); monitor `X-RateLimit-Remaining` headers |
| Attachment URLs expire before download | Medium | Permanent data loss | Download immediately after comment fetch; never queue URLs for later |
| Custom field choice ID mismatch | Medium | Silent data corruption | Pre-build lookup table; validate in sample migration of 100–500 tickets |
| Private category create failures | Medium | Ticket creation blocked | Use create-then-move pattern for private destination categories |
| Broken comment threading | Low | Agent confusion | Sort comments by `created_at` before replaying; verify with spot checks |
| Inline images break after Zendesk cancellation | High (if unaddressed) | Permanent data loss | Rewrite all inline image URLs during transformation phase |
| Integration disconnection post-cutover | Medium | Workflow disruption | Inventory and reconnect all integrations before go-live |
| DNS/MX propagation delay | Low | Email routing gap | Cut MX records 48 hours before scheduled go-live |

## What Customers and Agents Notice During Migration

With a properly executed delta-sync approach, customers notice nothing operationally. Historical tickets appear in HappyFox with full conversation history, timestamps, and attachments intact.

**What will change:**

- **Ticket IDs.** Zendesk's numeric IDs become HappyFox's prefixed IDs (e.g., `#HFS00000001`). Any external references, bookmarks, or hyperlinks to old ticket URLs will break. Store legacy Zendesk IDs in a searchable custom field so agents can look up old references. Consider setting up URL redirects if you have external systems linking to Zendesk ticket URLs.
- **Support portal URL.** Communicate the new URL to customers at least 1 week before cutover. If possible, set up a redirect from your old Zendesk help center URL.
- **Knowledge base.** If KB articles are migrated separately, there may be a temporary gap in self-service content. HappyFox documents KB APIs as export endpoints, not as part of the ticket import path — plan KB migration on a separate track. HappyFox's KB supports article import via API, but the structure differs from Zendesk Guide's section/article/translation hierarchy. ([support.happyfox.com](https://support.happyfox.com/kb/article/360-api-for-happyfox/))

**Agent retraining.** Zendesk Macros are not HappyFox Canned Actions, and Zendesk Triggers are not HappyFox Smart Rules. One Zendesk Trigger with 3 actions becomes 3 HappyFox Smart Rules. Budget 1–2 days for workflow retraining before cutover. Create a quick-reference mapping document showing each Zendesk macro's equivalent Canned Action name. ([support.happyfox.com](https://support.happyfox.com/kb/article/49-use-canned-actions-for-frequent-replies))

**SLA continuity.** Set up SLA rules in HappyFox before go-live so tickets created post-cutover immediately track against the correct targets. Migrated historical tickets will not retroactively calculate SLA compliance — only new activity on those tickets will be measured.

## Edge Cases and Known Limitations

**Inline images in ticket bodies.** Zendesk stores inline images as embedded HTML references hosted on Zendesk's CDN. To preserve them in HappyFox, download each image, upload it to HappyFox's inline attachment endpoint (which returns a temporary URL valid for 5 minutes), and rewrite the HTML `src` attribute before creating the ticket. If you skip this, images break as soon as you cancel your Zendesk contract. ([support.happyfox.com](https://support.happyfox.com/kb/article/1039-tickets-endpoint/))

**Category-scoped custom fields.** HappyFox custom fields can be associated with specific categories. If a Zendesk custom field applies globally but maps to a category-scoped field in HappyFox, tickets in non-associated categories will silently drop that field value. Audit field-category associations before loading.

**Contact deletion cascade.** In HappyFox, deleting a contact deletes all associated tickets. If you are cleaning up duplicate contacts post-migration, merge instead of delete. This is not reversible.

**Suspended tickets.** Zendesk holds spam and failed emails in a Suspended queue. Filter these out during extraction — do not migrate them unless you have a specific retention requirement.

**CCs and followers.** Zendesk handles CCs via `collaborator_ids`. Map these to HappyFox's equivalent CC fields, ensuring the referenced users exist in HappyFox first. Missing CC contacts are silently dropped, not flagged as errors.

**Multi-org Zendesk users.** Zendesk supports multiple organization memberships per user. HappyFox Contact Groups handle this natively (contacts can belong to multiple groups), but each association must be created explicitly — there is no bulk group-association endpoint. ([developer.zendesk.com](https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/))

**Comment volume on long-lived tickets.** Zendesk caps a ticket at 5,000 comments, paginated at 100 per page. A single ticket with 5,000 comments requires 50 paginated API calls to extract and 5,000 sequential POST calls to replay. A handful of these tickets can dominate your migration timeline — identify and plan for them during discovery. ([developer.zendesk.com](https://developer.zendesk.com/api-reference/ticketing/tickets/ticket_comments/))

**Zendesk Talk / Voice recordings.** Call recordings stored in Zendesk Talk are not part of the standard ticket export. They must be downloaded separately and attached to the corresponding HappyFox ticket as file attachments, or stored in an external system with a link in the ticket notes.

**Time zone and locale differences.** Zendesk stores timestamps in UTC. HappyFox also uses UTC internally but may display in the account's configured timezone. Verify that migrated timestamps align correctly by spot-checking a sample of tickets across different original creation dates.

## Validation and Testing

Never assume a `200 OK` response means the data is correct. Validate across five dimensions:

**1. Record-count reconciliation.** Compare total tickets, contacts, contact groups, public replies, private notes, and attachments between Zendesk and HappyFox. A mismatch above 0.1% should trigger investigation. Use Zendesk's `GET /api/v2/tickets/count` and HappyFox's list endpoints to get authoritative counts.

**2. Field-level spot checks.** Sample 50–100 tickets across different statuses, categories, and custom field types. Verify:
- Custom field values render correctly (not raw IDs or empty values)
- Dropdown and multi-select fields show the correct display text
- Attachment links are downloadable and not corrupted 0-byte files
- Comment threading order matches the original chronology
- Private notes remain private (not visible to contacts)
- Tags are present and correctly associated
- Requester and assignee are correct
- Legacy Zendesk Ticket ID custom field is populated and searchable
- Inline images render correctly (not broken image icons)

**3. Search UAT.** Prove that agents can find migrated tickets by HappyFox ID and by legacy Zendesk ticket number via the custom field. Test full-text search on ticket subjects and comment bodies.

**4. Workflow UAT.** Have 2–3 agents work in HappyFox for a day using migrated tickets. Test Canned Actions, Smart Rules, SLAs, email templates, and category routing against the new data. Verify that email notifications fire correctly (check spam folders).

**5. Rollback plan.** Keep Zendesk active (read-only) for at least 14 days post-cutover. If critical data issues surface, revert by redirecting email routing back to Zendesk and sending agents back to Zendesk. Note: any tickets created directly in HappyFox during the post-cutover period would need to be manually triaged or exported if you roll back. Do not try to reverse-migrate HappyFox data back to Zendesk after customers start interacting with migrated tickets.

## When to Build In-House vs. Use a Managed Migration Service

**Build in-house when:**
- You have fewer than 10,000 tickets
- No dropdown/multi-select custom fields, or only text-type custom fields
- No attachments or inline images
- You have a backend engineer with 2+ weeks of available capacity and API integration experience
- You can afford 1–2 full reruns if the first attempt has issues
- Your compliance requirements allow you to manage temporary data storage in-house

**Use a managed service when:**
- Ticket volume exceeds 50,000
- You have dropdown/multi-select custom fields requiring choice-ID mapping
- Attachments or inline images must be preserved
- Zero downtime is a hard requirement
- You need delta sync to minimize the cutover window
- Engineering time costs more than the migration service fee
- Compliance or audit requirements demand a documented chain of custody for migrated data

The real cost of a DIY migration is not the first API call. It is the weeks spent handling undocumented rate-limit edge cases, writing retry logic with exponential backoff, debugging silent custom field failures, manually validating attachment integrity across thousands of tickets, and rebuilding the pipeline when HappyFox's 10-minute lockout penalty burns through your migration window. At typical senior-engineer rates ($75–$150/hour), 3–6 weeks of in-house migration work represents $9,000–$36,000 in engineering time — before accounting for opportunity cost of delayed feature work.

ClonePartner has completed 1,500+ helpdesk migrations including Zendesk-to-HappyFox projects, handling custom field transformations, attachment preservation, inline image rewriting, and delta syncs with zero-downtime cutover.

> Need help migrating from Zendesk to HappyFox? Our engineers handle rate limits, custom field mapping, attachment preservation, and delta syncs — so your team doesn't have to. Book a free 30-minute scoping call.
>
> [Talk to us](https://cal.com/clonepartner/meet?duration=30)

## Frequently asked questions

### Can I migrate Zendesk to HappyFox without losing data?

Yes, but only if attachments and inline images are handled correctly during extraction. Zendesk attachment URLs expire quickly and must be downloaded immediately — not queued. Custom field values, tags, and conversation history can all be preserved with proper field mapping. Automation rules (Triggers, Macros, Views) cannot be migrated and must be rebuilt manually in HappyFox.

### How long does a Zendesk to HappyFox migration take?

Typical migrations under 100,000 tickets complete in 3–10 days including extraction, transformation, loading, and validation. Enterprise migrations exceeding 250,000 tickets with attachments may take 2–4 weeks. The primary bottleneck is Zendesk's 10 request-per-minute incremental export limit.

### What data cannot be migrated from Zendesk to HappyFox?

Zendesk Triggers, Automations, Macros, Views, and Side Conversations have no import path into HappyFox. Ticket metrics like first-reply time are Zendesk-internal audit fields with no write target in HappyFox. CSAT survey responses can be stored in a custom field but won't integrate with HappyFox's native survey system.

### Will my Zendesk ticket IDs be preserved in HappyFox?

No. HappyFox generates its own ticket IDs using a category prefix plus a sequential number (e.g., #HFS00000001). To retain the original Zendesk ticket ID for reference, create a custom text field in HappyFox and map the Zendesk ID to it during migration.

### Is a CSV export enough for a Zendesk to HappyFox migration?

Usually not if you care about full history. CSV exports strip attachments, break conversation threading, and lose timestamps. A full-fidelity migration requires comment threading, attachment downloads, public/private separation, and endpoint-aware replay via the APIs.