Zendesk to HubSpot Migration: The 2026 Technical Guide

Migrating from Zendesk to HubSpot Service Hub is a data engineering problem disguised as a platform switch. The challenge is not moving tickets — it is preserving the full context behind each ticket: associations between tickets, contacts, and companies; inline images and attachments; side conversations that have no native equivalent in HubSpot; and the macros your agents rely on daily.

All of this must pass through two separate rate-limiting regimes that throttle every API call on both sides. Choose HubSpot for the right reasons — stack consolidation, unified reporting, lower total cost of ownership — but plan the migration as an engineering project, not a drag-and-drop exercise.

This guide breaks down the API constraints, the complete data-mapping table, the structural mismatches that cause silent data loss, and the migration methods available so you can pick the approach that matches your volume, timeline, and risk tolerance.

For a deeper look at HubSpot Service Hub's architecture, pipelines, and help desk configuration, see The Ultimate 2026 Guide to HubSpot Service Hub.

Why RevOps Teams Are Moving from Zendesk to HubSpot Service Hub

The migration trend is driven by one word: consolidation. Teams running Zendesk for support alongside HubSpot for sales and marketing are paying for two platforms, maintaining two contact databases, and losing context at every handoff between them.

HubSpot Service Hub puts tickets, contacts, deals, and marketing engagement on a single CRM record. When an agent opens a ticket, they see the full customer lifecycle — last deal closed, last email opened, CSAT score — without switching tabs or relying on a fragile integration. HubSpot's Help Desk workspace can consolidate chat, email, form, calling, WhatsApp, and Facebook Messenger channels, and ticket-based workflows are available on Service Hub Professional and Enterprise. (knowledge.hubspot.com)

The native Zendesk-HubSpot integration confirms why a full migration matters: it is one-way, pushing ticket events to HubSpot's contact timeline, but it does not create actual HubSpot tickets or sync custom fields back. At user creation time, only the email address is synced. That is fine for temporary visibility during coexistence — it is not a replacement for migrating native tickets, activities, files, and automation into Service Hub. (support.zendesk.com)

Beyond architecture, total cost of ownership is forcing the issue. Zendesk's pricing scales aggressively — the Advanced AI add-on alone costs an additional $50 per agent per month on top of base Suite plans. When RevOps leaders compare that against a single HubSpot platform where marketing, sales, and service share one database, consolidation becomes the logical financial decision.

The API Bottleneck: Zendesk Export vs. HubSpot Import Limits

Every Zendesk-to-HubSpot migration is shaped by two rate-limiting regimes. Understanding them upfront determines whether your migration takes two days or two weeks — and whether it finishes cleanly or drops records silently.

Zendesk's Export Limits

Zendesk's Incremental Export API — the only efficient way to extract tickets at scale — is rate-limited independently of the general API. The cursor-based ticket export endpoint allows 10 requests per minute, with each page returning up to 1,000 tickets. Zendesk also enforces a separate 1-request-per-second limit on incremental exports. The High Volume API add-on increases throughput to 30 requests per minute, but requires a minimum of 10 agent seats and is only available on Suite Growth and above. (developer.zendesk.com)

The practical math: at 10 requests per minute returning 1,000 tickets per page, you can extract roughly 10,000 tickets per minute. A 500,000-ticket backlog takes at least 50 minutes — assuming zero 429 errors, zero network hiccups, and no sideloaded comment data. With comment sideloads (which you need for full ticket history), the payload grows and pagination slows.

Exceeding the limit triggers a 429 Too Many Requests response with a Retry-After header specifying how many seconds to wait. Ignoring that header gets your connection temporarily blocked. Zendesk recommends reducing per_page when requests slow down or time out. (developer.zendesk.com)

For a detailed breakdown of all three export methods, see 3 Advanced Ways to Export Tickets from Zendesk.

HubSpot's Import Limits

On the ingest side, HubSpot's rate limits depend on your app type and subscription tier:

These limits apply across all API calls to a single HubSpot account — not just your migration script. If your sales team is running workflows, your marketing platform is syncing contacts, and your migration script is creating tickets simultaneously, you are sharing one token bucket. HubSpot uses a token-bucket model: bursts are tolerated as long as you let the bucket refill. Sustained throughput without pauses triggers 429 errors. (developers.hubspot.com)

For bulk record loading, the Imports API is significantly more efficient than creating records one by one. HubSpot allows up to 80,000,000 rows per day via the Imports API, with individual files capped at 1,048,576 rows or 512 MB. This is why the safest pattern for base records (contacts, companies, tickets) is bulk import via CSV, then use APIs for notes, associations, and files. (developers.hubspot.com)

The CRM Search API has its own separate ceiling: 5 requests per second, 200 records per page, and a 10,000 records maximum per query. If you need to verify imported records against the target, segment queries by date range or property value. (developers.hubspot.com)

Why DIY Scripts Fail Here

The collision point is not either limit in isolation — it is the combined pipeline. A single Zendesk ticket with 5 comments and 3 attachments can require 10+ API calls on the HubSpot side alone:

1. Read from Zendesk (10 req/min for incremental export)
2. Download each ticket's attachments (separate API call per attachment, hitting Zendesk's general rate limit)
3. Upload each attachment to HubSpot's File Manager
4. Create the ticket in HubSpot with properties
5. Create the association between the ticket, contact, and company (separate Associations API call)
6. Create notes for each comment thread (separate Notes API call)

At 190 requests per 10 seconds, a migration of 100,000 tickets — each requiring roughly 10 HubSpot API calls — needs about 1,000,000 calls. That consumes an entire day's quota on a Professional plan, assuming perfect pacing with zero retries.

DIY scripts tend to fail in three specific ways. First, a naive "search-then-create per record" loop turns HubSpot's 5 rps search cap into the bottleneck. Second, upserting thousands of records too aggressively can trigger 423 Locked responses — locks that last 2 seconds per HubSpot's docs. Third, batch creates can partially fail: send a unique objectWriteTraceId per input and reconcile against the multi-status response instead of assuming all-or-nothing behavior. (developers.hubspot.com)

Zendesk to HubSpot Data Mapping: Tickets, Contacts, and Companies

Mapping between these two systems requires more than matching field names. It requires explicit association mapping, pipeline translation, and handling structural gaps where Zendesk objects have no direct HubSpot equivalent.

The Full Object Mapping

HubSpot's official Smart Transfer maps Zendesk Users to Contacts, Organizations to Companies, and Tickets to Tickets directly. Attachments, ticket comments as notes, and ticket conversations are handled as one-time post-sync transfers — not live-synced data. (knowledge.hubspot.com)

The Association Problem

HubSpot's CRM is graph-based. Every ticket must be explicitly associated with the correct contact and company using the Associations v4 API. An unassociated ticket is an orphaned ticket that no agent will find when searching by customer name.

The association requires the correct associationTypeId values: 16 for Ticket → Contact, 26 for Ticket → Company. Using the wrong type ID creates the record without error but silently fails to display the association in the UI.

{
  "fromObjectId": "TICKET_ID",
  "toObjectId": "CONTACT_ID",
  "category": "HUBSPOT_DEFINED",
  "definitionId": 16
}

The batch associations endpoint accepts up to 2,000 inputs per request, which is efficient for bulk operations. But migration order matters: contacts first, then companies, then tickets with associations. If your script creates tickets before contacts are imported, the association calls reference non-existent contact IDs. HubSpot does not always throw an error — some association attempts simply do nothing.

HubSpot imports can create associations in one file or across multiple files, but both methods depend on unique identifiers. If you omit the unique keys, HubSpot creates duplicate records instead of associating them. (knowledge.hubspot.com)

For a detailed guide on preserving user and organization relationships, see How to Migrate Users & Organizations Without Breaking History.

Statuses vs. Pipelines

Zendesk uses a fixed set of ticket statuses: New, Open, Pending, Solved, and Closed. HubSpot Service Hub uses Ticket Pipelines with customizable stages. Before migrating, map Zendesk's statuses to HubSpot pipeline stages:

• Zendesk New → HubSpot New
• Zendesk Open → HubSpot Waiting on Us
• Zendesk Pending → HubSpot Waiting on Customer
• Zendesk Solved / Closed → HubSpot Closed

For new HubSpot tickets, the required fields are Ticket name, Pipeline, and Ticket status. If you skip the pipeline or status, ticket creation will fail. For historical activities, include Activity date — if you do not, HubSpot stamps the activity with the import time, and existing notes cannot be updated via re-import. The first load needs to be right. (knowledge.hubspot.com)

Custom Fields, Tags, and Source IDs

Your Zendesk instance likely relies on dozens of custom ticket fields (e.g., "Product Version", "Escalation Reason"). These must be recreated as custom properties in HubSpot before the migration begins. Zendesk tags should be mapped to a dedicated multi-select property, allowing your team to filter legacy tickets without cluttering the new system.

What Breaks: Macros, Attachments, and Side Conversations

Every platform migration has structural mismatches — objects that exist in the source but have no direct equivalent in the target. These are the ones that silently degrade your migration quality.

Macros and Automations

Zendesk macros are pre-defined action sets: apply a tag, set a priority, assign a group, and insert a canned reply — all in one click. HubSpot has no single equivalent. You must decompose each macro into its constituent parts:

• Canned text → HubSpot Snippet (short reusable text blocks) or Template (full email templates)
• Field updates (status, priority, assignment) → HubSpot Workflow with ticket-based enrollment triggers
• Tag application → Update a multi-select custom property via workflow

This decomposition cannot be automated via API. Zendesk macros, triggers, and automations are API objects built from ticket actions, but HubSpot's Zendesk transfer documentation does not list any of those rule objects as transferred data. (knowledge.hubspot.com)

HubSpot now has help desk macros, each tied to a ticket-based workflow with support for multiple file attachments and a limit of 50 macros per account. Ticket-based workflows require Service Hub Professional or Enterprise. (knowledge.hubspot.com)

A practical remap:

• Zendesk canned reply macro → HubSpot macro or snippet
• Zendesk macro that changes fields/status → HubSpot macro + ticket-based workflow
• Zendesk trigger/automation → HubSpot workflow or routing rule
• Complex compound macro → Split into message content, workflow actions, and ownership rules

For teams with 50+ macros, this is a multi-day effort that should start weeks before the data migration. See Your Helpdesk Migration's Secret Saboteur: Automations, Macros, and Workflows.

Side Conversations

Zendesk Side Conversations are threaded discussions with external or internal parties that live alongside the main ticket thread. They can be email-based, Slack-based, or Microsoft Teams-based. HubSpot has no equivalent concept.

The only viable migration target is private notes associated with the ticket. Each side conversation thread should be serialized into a note with metadata preserved in the body: participants, timestamps, and channel.

The Zendesk Side Conversations API exposes these at GET /api/v2/tickets/{ticket_id}/side_conversations, with events (individual messages) at a separate endpoint. Extracting them requires per-ticket API calls — they are not included in the Incremental Export. For a 200,000-ticket migration where 15% of tickets have side conversations, that is 30,000 additional API calls just for the metadata, plus more for the message events. (developer.zendesk.com)

If exact side-conversation behavior matters, keep the original side conversation ID and participant metadata. Decide case by case whether the target should be a note, a linked file trail, or a linked child ticket. Flattening everything into one blob is fast — it is also the fastest way to make reopened escalations unreadable six months later.

Inline Images and Attachments

Zendesk ticket comments can contain inline images (embedded in the HTML body via Zendesk's CDN URLs) and file attachments (linked to the comment object). Both require special handling.

Inline images: The HTML body references Zendesk-hosted URLs. After migration, if you cancel your Zendesk subscription, those URLs return 403 Forbidden. Every inline image must be:

1. Downloaded from Zendesk
2. Uploaded to HubSpot's File Manager via the Files API
3. Given a new hosted URL
4. Rewritten in the ticket comment HTML to reference the HubSpot CDN URL

File attachments: Each attachment must be downloaded from Zendesk and uploaded to HubSpot. Zendesk caps ticket attachment size at 50 MB. HubSpot's File Manager has no strict per-file size limit for paid plans, but the email attachment limit is 20 MB — attachments larger than that can be stored in the File Manager but will not render inline in ticket correspondence. Zendesk also warns that content_url values may point to files hosted externally, so your downloader should not blindly forward Zendesk credentials when fetching them. (developer.zendesk.com)

On the HubSpot side, files must be uploaded first, then linked to notes through hs_attachment_ids. If you import from a URL, HubSpot's file import runs asynchronously — you must poll the task status before linking. Notes have a 65,536-character body limit, so very long ticket histories should be split into multiple notes rather than flattened into a single one. (developers.hubspot.com)

Ticket Priority Mismatch

Zendesk uses four priority levels: Low, Normal, High, Urgent. HubSpot's default hs_ticket_priority property only supports Low, Medium, High. There is no native "Urgent" option. Your options: create a custom priority property with your required values, or map Zendesk's "Urgent" to "High" and add a tag or flag property to preserve the distinction.

Ticket Conversations Are Not Importable

This is the single most painful limitation. HubSpot's Help Desk UI displays ticket history through conversations — the threaded message view agents actually use. Imported tickets do not generate conversation threads. When an agent opens a migrated ticket in the Help Desk view, they see the ticket metadata and associated notes, but the threaded conversation view is empty.

Historical ticket comments migrated as notes appear on the ticket's timeline but not in the customer portal or the Help Desk conversation thread. End customers viewing their ticket history through HubSpot's customer portal will only see the ticket subject — not the historical conversation.

HubSpot is actively evolving this area. As of 2026, HubSpot is replacing thread comments in Help Desk with notes. But importing historical conversation threads as first-class conversation objects is still not supported through any API.

Comparing Migration Methods: Smart Transfer, SaaS Tools, and Custom Engineering

There are four realistic approaches. Each trades off control, cost, and risk differently.

Method 1: HubSpot Smart Transfer

HubSpot's built-in Smart Transfer maps Zendesk Users to Contacts, Organizations to Companies, and Tickets to Tickets. Attachments, ticket comments as notes, and ticket conversations are handled as one-time post-sync transfers. HubSpot supports reverting a transfer if something goes wrong. (knowledge.hubspot.com)

Limitations: Custom objects are unsupported. Attachments and conversations are post-sync, not live-synced. No custom field transformation logic. Best suited for standard Zendesk structures with moderate history and low automation debt.

Method 2: HubSpot CSV Import

HubSpot's built-in import tool accepts CSV files for tickets, contacts, and companies. You can import multiple objects with associations using a two-file import or a single file with a common key column.

Limitations:

• Files capped at 20 MB on free tools
• Maximum 50 imports per day, with up to 3 running simultaneously
• No conversation thread import — only ticket properties
• No attachment handling via CSV
• Cannot set createdAt timestamps on imported tickets (they inherit import time)

For simple contact-and-ticket migrations without history, this works. For anything involving attachments, comments, or associations at scale, it does not.

Method 3: SaaS Migration Tools

Platforms like Help Desk Migration and Relokia offer a visual interface to map Zendesk fields to HubSpot properties and run the migration without writing code.

Strengths: Pre-built field mapping, contact/company deduplication, some ticket comment migration as notes, and trial/demo migrations to preview results.

Limitations: Attachment handling varies — some tools skip inline images or timeout on large files. Side conversations may not be supported or require a custom request. You are subject to the tool's own pacing logic and queue. Limited control over error handling and retry behavior.

Method 4: Custom Engineer-Led Migration

Best for: Large datasets (50,000+ tickets), complex custom fields, strict data-integrity requirements, and zero-downtime mandates.

Custom scripts handle the full pipeline: Zendesk extraction with exponential backoff, data transformation, HubSpot ingestion with association management, attachment re-hosting, and inline image URL rewriting.

Strengths: Full control over error handling, retry logic, and pacing. Handles side conversations, inline image rewriting, and custom field transformations. Supports delta sync for zero-downtime cutover. Can be tuned to your specific API limits.

Limitations: Requires engineering time (internal or outsourced). Higher upfront cost than SaaS tools.

The native path is fine when you have one support model, moderate history, and low automation debt. Move to custom engineering when any of these are true: multiple pipelines or brands, large attachment volume, strict public/private comment fidelity, heavy macro logic, or a hard requirement to keep agents in Zendesk until the last delta sync.

The Zero-Downtime Execution Plan

A zero-downtime migration means your support team keeps working in Zendesk until the exact cutover moment, with no maintenance window where tickets go unanswered. Here is how to structure it.

Step 1: Pre-Migration Setup (Week 1)

• Audit Zendesk: Count tickets, comments, attachments, custom fields, macros, and side conversations. Use the Zendesk API to pull real counts — the admin UI often shows approximate numbers.
• Build HubSpot pipelines: Create ticket pipeline stages matching Zendesk's statuses. Pre-create all custom properties, dropdown values, and multi-select fields for tags.
• Create source ID fields: Add custom properties in HubSpot for Zendesk ticket ID, user ID, organization ID, comment ID, and attachment ID. These are critical for delta sync and QA.
• Rebuild macros: Start converting Zendesk macros into HubSpot Snippets, Templates, Workflows, and help desk macros. This is the longest manual task.
• Map agents to owners: Create HubSpot users for each Zendesk agent and note the owner IDs for the migration script.

Step 2: Historical Bulk Migration (Days 1–3)

Run the full extraction from Zendesk using the Incremental Export API with cursor-based pagination. Import into HubSpot in order: contacts first, companies second, tickets with associations third, notes and attachments last. Use the Imports API for base records and the Notes/Files APIs for historical activities.

Include the original Activity date on every note import. If you skip it, HubSpot stamps the note with the import time, wrecking chronology. Existing notes cannot be corrected with a re-import, so validate timestamps and authorship before scaling up. (knowledge.hubspot.com)

Track the cursor or end_time from the last successful export page — this is your delta sync starting point. The start_time for cursor-based exports must be at least one minute in the past. (developer.zendesk.com)

Step 3: Delta Sync (Day 3 → Cutover)

Periodically re-run the incremental export starting from the saved cursor. This pulls only tickets created or updated since the last sync. Apply the same transformation and load pipeline to the delta records. Repeat every few hours — or more frequently — as cutover approaches.

For a detailed explanation of how delta syncs keep support running during a migration, see Zero-Downtime Helpdesk Migration: How to Keep Support Running During the Move.

Step 4: Cutover

• Run one final delta sync. Because Zendesk cursor exports trail by at least one minute, leave a short buffer before the final switch.
• Verify record counts: total tickets, contacts, companies, and notes in HubSpot vs. Zendesk.
• Spot-check 50–100 tickets for correct associations, attachment links, and note content.
• Switch agent routing to HubSpot. Disable Zendesk inbound channels.
• Keep Zendesk in read-only mode for 30 days as a safety net.

Step 5: Post-Migration Validation

• Verify no tickets were orphaned (missing contact or company associations).
• Confirm inline image URLs resolve to HubSpot CDN, not Zendesk.
• Test every rebuilt workflow and snippet with real tickets.
• Spot-check that timestamps reflect original creation dates, not the migration date.
• Run a CSAT survey comparison if you migrated satisfaction data to a custom field.

For a comprehensive post-migration testing checklist, see Post-Migration QA: 20 Tests to Run After Your Helpdesk Migration.

A real go-live check is not just ticket-count parity. It is ticket parity, association parity, readable timeline order, working attachments, and agents being able to reopen random old tickets without asking where the history went. That is the standard to aim for.

Choose the Migration Shape Before You Choose the Tool

If your Zendesk instance is simple — moderate ticket volume, standard fields, limited history — start with HubSpot's Smart Transfer and test it hard. If you need faithful ticket history, inline image rewriting, side conversation preservation, rebuilt automation, and a live delta sync up to cutover, treat the job as a data engineering project.

The hardest part of this migration is not moving data. It is preserving context — the thread of understanding that connects a ticket to a customer to a company to a conversation. That is what separates a successful migration from one where agents spend weeks asking customers to re-explain their history.