How to Migrate HappyFox to Zendesk: The Technical Guide

What Is a HappyFox to Zendesk Migration?

A HappyFox to Zendesk migration is the process of moving tickets, contacts, contact groups, custom fields, knowledge base articles, tags, and attachments from HappyFox Help Desk into Zendesk Support while preserving conversation history, timestamps, and relational integrity.

Most teams move for stack standardization, integration breadth, or automation maturity — not because HappyFox cannot handle ticketing. Treat this as a data-model redesign with history preservation, not a CSV exercise.

Why Teams Move from HappyFox to Zendesk

Teams typically leave HappyFox for three platform-specific reasons:

1. Ecosystem and integrations. Zendesk's marketplace lists over 1,500 pre-built integrations (as of early 2025) compared to HappyFox's approximately 15 native integrations. Teams outgrow HappyFox when they need tighter connections to CRMs, BI tools, or developer platforms.
2. API scalability. HappyFox's API caps at 100–800 requests per minute depending on plan, and exceeding the threshold triggers a full 10-minute lockout. Zendesk's Enterprise plans support 700 req/min with a High Volume add-on path to 2,500 req/min, with no comparable lockout penalty.
3. AI and automation maturity. HappyFox's AI features (AI Copilot, Assist AI, Autopilot) are separate paid add-ons with workflow execution caps. Zendesk bundles AI-powered triage and agent copilot into its Suite plans.

Architectural Differences That Make This Migration Non-Trivial

Categories vs. Groups. HappyFox organizes tickets into Categories — each with a unique prefix, associated custom fields, and optional Brand linkage. Zendesk has no single equivalent. Depending on your structure, HappyFox Categories may need to map to Zendesk Groups, Brands, Ticket Forms, or a combination of all three.

Worked example: Suppose you have a HappyFox Category called "Billing – US" with prefix BUS, associated with Brand "US Operations," and with custom fields "Invoice Number" and "Payment Method." In Zendesk, this becomes: a Group named "Billing – US" (for agent routing), a Brand "US Operations" (for portal separation, Enterprise plan required), and a Ticket Form "Billing" (for field visibility, Professional plan required) that includes the "Invoice Number" and "Payment Method" fields. The prefix BUS-1234 is stored in external_id as HF-BUS-1234.

Contact Groups vs. Organizations. HappyFox Contact Groups are end-user visibility constructs with tagged domains and shared ticket access settings. Zendesk Organizations serve a similar role but have different permission models and no concept of "tagged domains" as a native field.

Thread model. HappyFox stores ticket updates (replies, private notes, status changes) as a flat update stream. Zendesk uses a structured comment model where each comment has an author_id, public flag, and created_at timestamp. Mapping between these requires per-ticket iteration — there is no bulk thread export.

Category-scoped fields. HappyFox lets you associate specific custom fields with specific Categories, and choice values are written using option IDs. In Zendesk, ticket fields are globally defined, dropdown values use tag values instead of display labels, and category-scoped field visibility maps to Ticket Forms (available on Professional plans and above). (support.happyfox.com)

Ticket numbering. HappyFox category prefixes influence display ticket numbers. Zendesk assigns its own ticket IDs. Preserve the original HappyFox display number in external_id or a dedicated custom field so agents can search by the old number post-migration.

How Do HappyFox Objects Map to Zendesk?

What Has No Clean Equivalent on Zendesk?

• HappyFox parent-child custom field dependencies — Zendesk supports conditional fields, but the dependency logic must be rebuilt in Ticket Form configuration. Nested multi-level dependencies (3+ levels) may require flattening.
• Category-scoped custom fields — Maps to Zendesk Ticket Forms, available on Professional plans and above.
• Contact Group tagged domains — No native Zendesk field. Store as an Organization custom field or in notes.
• Contact Group ticket visibility by category — Zendesk Organizations can share tickets, but they do not reproduce HappyFox's category-scoped sharing model. (support.happyfox.com)
• Category prefixes and ticket numbers — Zendesk assigns its own IDs. Preserve the original in external_id.
• Smart Rule and automation logic — Must be manually reconstructed as Zendesk Triggers and Automations. For guidance, see how to handle automation migration.
• Historical SLA metrics — Zendesk explicitly does not support SLA metrics on imported tickets. Tag imported tickets and exclude them from SLA reports. (developer.zendesk.com)

How Do You Export Data from HappyFox?

Native CSV Export Limitations

HappyFox provides a CSV/XLS ticket export via Reports → Exports. This export includes ticket metadata, system fields, custom field values, and the initial message subject and body. It does not include staff replies, client replies, or private notes made after ticket creation. This limitation makes the native CSV export unsuitable for full-fidelity migrations.

Knowledge Base articles can be exported separately to CSV with fields including Article ID, Title, Section Name, Content, Tags, Created By, and Created At.

HappyFox API: Endpoints, Pagination, and Rate Limits

Full ticket extraction — including thread history — requires the HappyFox REST API.

HappyFox supports date-window filtering via the q= search parameter, which is essential for delta syncs:

# Full extract window
/api/1.1/json/tickets/?size=50&page=1&status=_all&q=created-on-or-after:'2024/01/01'+created-before:'2024/07/01'
 
# Delta sync window
/api/1.1/json/tickets/?size=50&page=1&status=_all&q=last-modified-on-or-after:'2024/07/11'

Rate limits by plan:

Auth: Basic HTTP authentication using API Key and Auth Code. JSON is the recommended response format. EU-hosted accounts use <instance>.happyfox.net instead of .happyfox.com. (support.happyfox.com)

Attachment URL Behavior

Attachments are where many DIY plans break. HappyFox attachment URLs returned inside ticket updates include temporary access credentials that expire within minutes (observed TTL of approximately 15–30 minutes, though HappyFox does not document a guaranteed TTL). You must download attachments during extraction, not store source URLs for later retrieval.

Inline images in ticket HTML bodies also reference HappyFox-hosted URLs — these will continue to resolve temporarily but will break when your HappyFox account is deactivated. Download and re-upload all inline images as Zendesk-hosted attachments during migration. (support.happyfox.com)

How Do You Import Data into Zendesk?

Zendesk Sandbox Provisioning

Before importing into production, run a full test migration in a Zendesk sandbox. Sandbox instances are available on Professional plans and above. You can provision a sandbox from Admin Center → Account → Sandbox — it mirrors your production configuration including custom fields, groups, and brands. On Enterprise plans, you get a premium sandbox that includes a copy of production data. If you are on a Team or Growth plan without sandbox access, create a separate trial instance for testing.

The Ticket Import API Is Required for Full-Fidelity Migration

Zendesk's Ticket Import API (/api/v2/imports/tickets) is the only endpoint that lets you set created_at, updated_at, and solved_at on imported tickets. The standard Tickets API does not support backdating. Zendesk's native Data Importer handles users, organizations, and custom object records — but not tickets. (support.zendesk.com)

Key capabilities of the Ticket Import API:

• Set historical timestamps on both tickets and individual comments
• Include multiple comments per ticket in a single request
• Skip triggers and automations (by design — prevents notification spam during migration)
• Use archive_immediately=true to send closed tickets directly to the archive (recommended for datasets over 750,000 tickets)
• Attach files by uploading via the Upload API first, then referencing the token in comment payloads

Batch import: Use /api/v2/imports/tickets/create_many to import up to 100 tickets per request. This endpoint runs asynchronously through a job_status — treat async job completion, not HTTP acceptance, as the definition of success. (developer.zendesk.com)

Files must be uploaded to Zendesk first through POST /api/v2/uploads?filename=..., then attached to the imported comment using the returned upload token. That token is valid for 60 minutes. (developer.zendesk.com)

Zendesk API Rate Limits by Plan

Throughput Planning

On an Enterprise plan (700 req/min), using batch imports of 100 tickets per request, theoretical maximum throughput is high — but that assumes zero latency and no attachment uploads. Real-world throughput with attachment uploads, error handling, and retries typically lands at 3,000–8,000 tickets per hour depending on average attachment count and comment depth per ticket.

Each attachment upload consumes one API request. A ticket with 5 comments and 3 attachments costs at minimum 4 API calls (1 batch slot + 3 upload calls). Use a pilot batch of 500–1,000 tickets to calibrate realistic throughput for your dataset rather than relying on vendor ceilings. (developer.zendesk.com)

Common Zendesk Import API Error Responses

Understanding rejection reasons accelerates debugging:

Which Migration Approach Should You Use?

Which Approach Fits Your Team?

• Small team (<5,000 tickets, simple fields): A third-party SaaS tool or a careful custom script. Budget 1–2 weeks of engineering time for the script path. Third-party SaaS tools typically charge $1–$5 per 1,000 records.
• Mid-market (5,000–100,000 tickets, custom fields, multi-brand): Custom script or managed service. The complexity of Category-to-Group/Brand mapping and dependent custom fields usually tips the balance toward managed service.
• Enterprise (100K+ tickets, compliance requirements): Managed service. The combination of rate limit management, attachment volume, delta sync for cutover, and validation at scale makes DIY scripts a significant engineering distraction.

Step-by-Step HappyFox to Zendesk Migration Process

The order of operations matters. Importing tickets before their associated users or organizations exist in Zendesk will cause failures — the Ticket Import API requires requester_id to reference an existing, active Zendesk user.

Step 1: Extract Reference Data from HappyFox

Pull Categories, Statuses, Priorities, Staff, Custom Field definitions, and Contact Groups first. These are small datasets and establish the ID mapping tables you need for everything else.

import requests
from requests.auth import HTTPBasicAuth
 
HF_BASE = "https://yourinstance.happyfox.com/api/1.1/json"
HF_AUTH = HTTPBasicAuth("<API_KEY>", "<AUTH_CODE>")
 
categories = requests.get(f"{HF_BASE}/categories/", auth=HF_AUTH).json()
statuses = requests.get(f"{HF_BASE}/statuses/", auth=HF_AUTH).json()
priorities = requests.get(f"{HF_BASE}/priorities/", auth=HF_AUTH).json()
staff = requests.get(f"{HF_BASE}/staff/", auth=HF_AUTH).json()

Step 2: Create Zendesk Organizations, Groups, and Users

Map HappyFox Contact Groups → Zendesk Organizations. Map HappyFox Categories → Zendesk Groups. Create all agents and end-users in Zendesk before importing any tickets.

Use Zendesk's /api/v2/users/create_many endpoint (up to 100 users per request) for contacts. Build a lookup table mapping HappyFox contact IDs to Zendesk user IDs — you need this for every ticket import.

Note that bulk user imports via the API may not be enabled by default on all plans and can return 403 until Zendesk Support enables the feature. (support.zendesk.com)

Step 3: Create Custom Fields in Zendesk

Create ticket custom fields and user custom fields in Zendesk that mirror your HappyFox schema. Key type mappings:

Store a field ID mapping table (HappyFox field ID → Zendesk field ID, plus option value mappings for dropdowns). Build explicit enum translation tables for choice fields — this is where most rework happens.

Example enum mapping for a "Region" dropdown:

If you use category-scoped fields in HappyFox, set up corresponding Ticket Forms in Zendesk to control field visibility.

Step 4: Extract and Transform Tickets

Paginate through all HappyFox tickets. For each ticket, fetch the full detail including all updates (replies, notes, status changes). Transform each update into a Zendesk comment object with the correct author_id, public flag, html_body, and created_at.

import time
 
def extract_all_tickets(base_url, auth, page_size=50, rate_limit=400):
    safe_limit = rate_limit * 0.8  # Stay at 80% to avoid 10-min lockout
    delay = 60.0 / safe_limit
    page = 1
    all_tickets = []
    while True:
        resp = requests.get(
            f"{base_url}/tickets/",
            params={"page": page, "size": page_size},
            auth=auth
        )
        if resp.status_code == 429:
            print("Rate limited. Sleeping 600 seconds.")
            time.sleep(600)  # HappyFox locks out for 10 minutes
            continue
        data = resp.json()
        tickets = data.get("data", [])
        if not tickets:
            break
        all_tickets.extend(tickets)
        page += 1
        time.sleep(delay)
    return all_tickets

Download attachments during this step. HappyFox attachment URLs expire within minutes. Do not store source URLs for later.

HappyFox to Zendesk Ticket Transformation Example

HappyFox API response (abbreviated):

{
  "id": 1234,
  "display_id": "SUP-1234",
  "subject": "Cannot reset password",
  "category": {"id": 5, "name": "Support"},
  "priority": {"id": 2, "name": "High"},
  "status": {"id": 3, "name": "Closed"},
  "user": {"id": 101, "name": "Jane Doe", "email": "jane@example.com"},
  "assigned_to": {"id": 7, "name": "Agent Smith"},
  "created_at": "2024-03-15T10:30:00Z",
  "last_modified": "2024-03-16T14:22:00Z",
  "custom_fields": [
    {"id": 12, "value": 42, "value_text": "North America"}
  ],
  "tags": ["password", "urgent"],
  "updates": [
    {
      "id": 5001,
      "timestamp": "2024-03-15T10:30:00Z",
      "by": {"id": 101, "type": "user"},
      "message": {"text": "I can't reset my password. Keep getting an error."},
      "attachments": []
    },
    {
      "id": 5002,
      "timestamp": "2024-03-15T11:45:00Z",
      "by": {"id": 7, "type": "staff"},
      "message": {"text": "Can you share a screenshot of the error?"},
      "attachments": [],
      "message_type": "reply"
    },
    {
      "id": 5003,
      "timestamp": "2024-03-15T14:00:00Z",
      "by": {"id": 7, "type": "staff"},
      "message": {"text": "Escalating to engineering — auth service issue."},
      "attachments": [],
      "message_type": "private_note"
    }
  ]
}

Transformed Zendesk Import API payload:

{
  "ticket": {
    "subject": "Cannot reset password",
    "requester_id": 900001,
    "assignee_id": 900007,
    "group_id": 360000005,
    "status": "closed",
    "priority": "high",
    "external_id": "HF-SUP-1234",
    "created_at": "2024-03-15T10:30:00Z",
    "updated_at": "2024-03-16T14:22:00Z",
    "solved_at": "2024-03-16T14:22:00Z",
    "tags": ["password", "urgent", "imported_from_happyfox"],
    "custom_fields": [
      {"id": 360000012, "value": "region_north_america"}
    ],
    "comments": [
      {
        "author_id": 900001,
        "html_body": "I can't reset my password. Keep getting an error.",
        "created_at": "2024-03-15T10:30:00Z",
        "public": true
      },
      {
        "author_id": 900007,
        "html_body": "Can you share a screenshot of the error?",
        "created_at": "2024-03-15T11:45:00Z",
        "public": true
      },
      {
        "author_id": 900007,
        "html_body": "Escalating to engineering — auth service issue.",
        "created_at": "2024-03-15T14:00:00Z",
        "public": false
      }
    ]
  }
}

Key transformation decisions visible in this example: HappyFox user.id 101 → Zendesk requester_id 900001 (from the user mapping table), HappyFox option ID 42 → Zendesk tag value region_north_america (from the enum mapping table), HappyFox message_type: "private_note" → Zendesk public: false, and the original display ID preserved in external_id.

Step 5: Upload Attachments and Import Tickets

For each ticket with attachments: download from HappyFox (if not already cached), upload to Zendesk via the Upload API (POST /api/v2/uploads), capture the returned token (valid for 60 minutes), and include it in the comment payload.

Batch-import tickets using /api/v2/imports/tickets/create_many in groups of 100. Set archive_immediately=true for closed/resolved tickets in high-volume migrations.

batch = []
 
for hf_ticket in all_tickets:
    files = download_happyfox_files(hf_ticket)
    upload_tokens = [zendesk_upload(f) for f in files]
 
    zd_ticket = {
        'subject': hf_ticket['subject'],
        'requester_id': user_map[hf_ticket['user']['id']],
        'organization_id': org_map.get(hf_ticket.get('contact_group_id')),
        'group_id': group_map[hf_ticket['category']['id']],
        'brand_id': brand_map.get(hf_ticket.get('brand_id')),
        'created_at': hf_ticket['created_at'],
        'updated_at': hf_ticket['last_modified'],
        'solved_at': hf_ticket.get('closed_at'),
        'external_id': f"HF-{hf_ticket['display_id']}",
        'tags': normalize_tags(hf_ticket.get('tags', [])) + ['imported_from_happyfox'],
        'custom_fields': map_custom_fields(hf_ticket),
        'comments': build_comments(hf_ticket, upload_tokens, user_map)
    }
 
    batch.append(zd_ticket)
    if len(batch) == 100:
        resp = post('/api/v2/imports/tickets/create_many', {'tickets': batch})
        job_id = resp['job_status']['id']
        result = wait_for_job_status(job_id)
        log_failures(result)  # Dead-letter queue for failed tickets
        batch = []
 
# Flush remaining
if batch:
    resp = post('/api/v2/imports/tickets/create_many', {'tickets': batch})
    wait_for_job_status(resp['job_status']['id'])
 
# Retry rules:
# HappyFox 429 -> sleep 600 seconds (10-minute lockout)
# Zendesk 429 -> honor Retry-After header (typically 30-60 seconds)
# 5xx -> exponential backoff (1s, 2s, 4s, 8s, max 60s) + dead-letter queue after 3 retries

Step 6: Configure Email Channels Before Go-Live

Before cutting over inbound email, configure your email channels in Zendesk (Admin Center → Channels → Email). If you switch MX records or forwarding rules before Zendesk is fully configured, inbound emails may land in Zendesk's Suspended Tickets queue instead of creating new tickets. Verify channel configuration, trigger rules, and routing in your sandbox before touching DNS.

Step 7: Validate and Reconcile

After import, run record-count reconciliation and field-level spot checks. See the validation section below for the full protocol.

How Long Does a HappyFox to Zendesk Migration Take?

Realistic timeline for a mid-size migration (10,000–50,000 tickets):

Timeline scales primarily with ticket count, attachment volume, and custom field complexity — not agent count. Datasets under 5,000 tickets can complete in under a week. Enterprise migrations with 100K+ tickets and complex custom fields may take 3–4 weeks. For a broader planning benchmark, see the help desk data migration timeline guide.

Choose the cutover style based on operational risk:

• Big-bang: Switch everything at once over a weekend. Fits single-brand, lower-volume teams.
• Phased: Migrate department-by-department or brand-by-brand. Fits multi-brand or complex routing setups.
• Delta sync: Run a historical backfill first, then a final delta based on last-modified-on-or-after filters before switching channels. Lets agents keep working in HappyFox until Zendesk is validated.

Risk Register

Rollback plan: Keep HappyFox active (read-only or full) for at least 2 weeks post-cutover. If critical data issues surface, you can revert to HappyFox while debugging. Zendesk imported tickets can be bulk-deleted using the /api/v2/tickets/destroy_many endpoint, but this is limited to 100 ticket IDs per request with its own rate constraints — plan for slow cleanup on large datasets. For a comprehensive pre-cutover plan, reference the Zendesk migration checklist.

What Do Customers and Agents Notice During Migration?

With proper planning, customers notice nothing. The standard approach is a zero-downtime migration where HappyFox remains live for incoming tickets while historical data is loaded into Zendesk. A final delta sync captures any tickets created during the migration window.

What matters for customer trust:

• Ticket history continuity. When a customer opens a follow-up, agents must see the full conversation — not just metadata. This requires migrating all thread replies and private notes, not just the initial ticket description.
• SLA impact. Zendesk explicitly warns that metrics and SLAs are not supported for imported tickets. Tag imported tickets and exclude them from reports. New SLA tracking starts from your Zendesk go-live date. (developer.zendesk.com)
• CSAT data. Historical satisfaction survey results from HappyFox cannot be migrated into Zendesk's CSAT system. Export and archive this data separately (CSV or database) for reporting continuity.
• Ticket numbers change. Zendesk assigns its own ticket IDs. If you preserve the original HappyFox display number in external_id, agents can search by the old number using external_id:HF-SUP-1234 during the transition period. Keep this visible for at least the first month post-cutover.

Change management: Brief your support team on the new interface at least 1 week before cutover. Prepare a customer-facing FAQ or status page update if your support portal URL changes. Set up URL redirects from the old HappyFox support portal to Zendesk Guide. Automations and SLAs from HappyFox will not migrate and must be rebuilt manually — see our guide to migrating automations, macros, and workflows.

Data Privacy and Compliance Considerations

Migrations involve transferring potentially sensitive customer data between platforms. Address these requirements before starting:

• Data residency. HappyFox and Zendesk may host data in different regions. Zendesk offers data center locations in the US, EU (Frankfurt), and Australia. If your HappyFox instance is EU-hosted (.happyfox.net), confirm your Zendesk instance is also EU-hosted to avoid cross-border data transfer issues under GDPR.
• PII handling during migration. Migration scripts and intermediate storage (local files, staging databases) will contain customer PII. Encrypt data at rest during the migration process, use HTTPS for all API calls (both platforms enforce TLS), and delete intermediate files after successful import and validation.
• GDPR right-to-erasure timing. If you receive deletion requests during the migration window, apply them to both HappyFox and the migration dataset before importing into Zendesk.
• Compliance documentation. For HIPAA or SOC 2 environments, document the migration as a data processing activity: what data was transferred, when, by whom, and what controls were in place. If using a managed service, ensure they can provide a DPA (Data Processing Agreement) and evidence of their own compliance certifications.

Edge Cases and Known Limitations

Inline images. Images embedded in HappyFox ticket bodies reference HappyFox-hosted URLs. After migration, these URLs still resolve — until HappyFox deactivates your account. Your migration script must parse the HTML, download each image, upload it to Zendesk via the Upload API, and rewrite the <img src="..."> tag URL to reference the Zendesk-hosted version. Do not defer this — it cannot be fixed retroactively once HappyFox access is lost.

Suspended and deleted users. Zendesk's Import API requires all requesters and assignees to be active users. If HappyFox tickets reference deleted contacts, you must either recreate them as Zendesk end-users or map those tickets to a placeholder account like "Former Customer" (former_customer@yourdomain.com). Contacts with invalid email formats will also be rejected — sanitize these before import.

Duplicate contacts. HappyFox allows contacts with the same email across different Contact Groups. Zendesk identifies users by email uniquely. Deduplicate before import or the second import will silently update the first user's record, potentially overwriting organization membership and custom field values.

Multi-brand mapping. If you use HappyFox's multi-brand feature (Categories associated with Brands), you need Zendesk's multi-brand feature (available on Enterprise and Enterprise Plus plans) to maintain separation. On lower Zendesk plans, brands collapse into a single instance — plan accordingly.

Knowledge Base migration. HappyFox KB exports as flat CSV. Zendesk Guide uses a Category → Section → Article hierarchy. This is effectively a separate sub-migration:

• Map HappyFox KB sections to Zendesk Guide sections.
• Use the Help Center API (POST /api/v2/help_center/sections/{id}/articles) to create articles with preserved HTML content.
• Sanitize HTML: remove HappyFox-specific CSS classes, fix relative URLs, and ensure images are re-hosted on Zendesk.
• Handle internal KB links: rewrite any links between articles to reference the new Zendesk Guide URLs.
• Set up URL redirects from old HappyFox KB URLs to new Zendesk Guide URLs to preserve SEO value and avoid broken bookmarks.
• Restricted/private articles in HappyFox need permission mapping to Zendesk Guide user segments.

Attachment size. Zendesk has a 50 MB per-attachment limit on API uploads. HappyFox does not enforce a comparable limit. Audit for oversized files before import and handle them separately (e.g., link to external storage).

CCs and followers. Mapping secondary ticket participants requires the collaborator_ids array in the Zendesk import payload. HappyFox stores CCs differently per update. Failure to map these means dropped visibility for stakeholders on multi-party conversations.

Choice field values. HappyFox writes dropdown values using option IDs in API payloads (e.g., 42). Zendesk dropdowns use tag values (e.g., region_north_america), not display labels. Build explicit enum translation tables — this is a common source of silent data corruption if handled carelessly. A wrong mapping doesn't cause an error; it just writes the wrong value. (support.happyfox.com)

Triggers on imported tickets. Triggers and automations do not run on tickets imported via the Ticket Import API. This is intentional — it prevents notification spam during migration. Triggers will fire if an imported ticket is subsequently updated by an agent or end-user.

Historical SLA metrics. Zendesk does not support SLA metrics on imported tickets. Tag imported tickets and exclude them from SLA reporting. (developer.zendesk.com)

How Do You Validate a HappyFox to Zendesk Migration?

Validate at three levels: counts, field fidelity, and operational behavior. If you only compare record counts, you will miss the failures agents actually care about — wrong requester, broken attachments, public notes imported as internal, or tickets routed to the wrong group.

Record-Count Reconciliation

Compare total counts for every migrated object type:

• Total tickets in HappyFox (by status) vs. Zendesk (filter by imported_from_happyfox tag)
• Total contacts in HappyFox vs. Zendesk end-users
• Total contact groups vs. Zendesk organizations
• Total KB articles exported vs. created in Zendesk Guide
• Total attachments extracted vs. successfully uploaded

Field-Level Spot Checks

Select a random sample of 50–100 tickets across different Categories, Statuses, and date ranges. For each, verify:

• Subject and description match
• All comments/replies are present and in correct chronological order
• Custom field values are correct (especially dropdown mappings — check tag values, not display labels)
• Attachments are present and downloadable
• Inline images render correctly (not broken HappyFox URLs)
• created_at and updated_at timestamps match source
• Assignee and requester are correct
• Public vs. private note visibility is correct
• Organization assignment matches the original Contact Group

UAT Protocol

Have 2–3 support agents review tickets from their own queue. They will catch mapping errors that automated checks miss — wrong group assignments, missing context in notes, or broken inline images. Run portal visibility tests with end-user accounts that represent shared and non-shared access to verify that organization-level ticket sharing behaves as expected.

Zendesk recommends tagging imported tickets. This tag gives you a clean UAT slice, easier cleanup logic if a re-import is needed, and a way to exclude imported history from metrics.

Go-live criteria checklist:

1. Record-count reconciliation complete (all object types within 0.1% tolerance)
2. Attachment spot-check passed (random sample of 20+ tickets with attachments)
3. Public/private note visibility verified on 10+ tickets
4. Custom field value mapping verified (all dropdown enums checked)
5. Automation and trigger rebuild signed off by operations lead
6. Email channel routing tested with inbound test messages
7. Final delta dry run clean (zero failures on delta batch)
8. Agent training session completed

For a full post-migration testing framework, see the post-migration QA checklist. For day-of checks, use the Zendesk migration checklist.

Should You Build In-House or Use a Managed Service?

When In-House Makes Sense

• Fewer than 5,000 tickets with minimal custom fields
• Your team has Python/Node engineers available for 2+ weeks
• Simple Category structure (no multi-brand, no dependent custom fields)
• You are comfortable managing rate limits, retries, attachment uploads, and ID mapping yourself
• No compliance requirements that demand documented chain of custody

When In-House Does Not Make Sense

• 10,000+ tickets with deep conversation threads
• Multi-brand HappyFox setup requiring Zendesk Brand mapping
• Parent-child dependent custom fields requiring conditional field logic
• Zero-downtime requirement with delta sync
• Compliance requirements (HIPAA, SOC 2, GDPR) that need documented data processing controls
• Your engineering team's time is better spent on product work

The hidden cost of DIY is not the initial script — it is the debugging. Broken ID mappings, 429 lockouts, attachment upload failures, and edge cases in thread ordering typically add 40–60% more engineering time than the initial estimate. A script that "works" on the first 1,000 tickets often fails on tickets #3,001–#3,500 due to edge cases in data (null fields, special characters in subjects, orphaned user references).