Zendesk to HubSpot Knowledge Base Migration: Technical Guide

Moving a knowledge base from Zendesk Guide to HubSpot Service Hub is not a content copy job. The article HTML, category hierarchy, inline images, original timestamps, and SEO equity all require separate handling — and every native tool available today silently drops at least one of those. This guide walks through the structural differences, migration methods, and the specific failure modes that catch teams off guard so you can choose the right approach for your volume and risk tolerance.

For the broader migration covering tickets, contacts, and CRM objects, see Zendesk to HubSpot Migration: The 2026 Technical Guide. If you need to export raw article data first, start with How to Export Data from Zendesk Guide: Methods, Limits & Formats.

Why Zendesk to HubSpot Knowledge Base Migrations Fail

Teams assume the move is straightforward because the article content is "just HTML." In practice, four categories of data loss happen repeatedly:

Formatting destruction. HubSpot's native import tool does not support tables — it replaces them with a placeholder. Custom styled <div> elements are stripped, and side-by-side images are forced into a vertical stack. HubSpot's documentation warns that you will receive a CSV of articles that need manual fixing after import. (knowledge.hubspot.com)

Metadata loss. When importing via CSV or Smart copy, key fields like the original article create date, last updated date, and author attribution cannot be set. HubSpot's Knowledge Base import maps URL, Title, Category, Subcategory, Keywords, Meta description, Article Body, and Subtitle — nothing else. Your article history effectively resets to the date of the import, and every article is attributed to the user who ran the upload. (knowledge.hubspot.com)

Broken inline images. Zendesk-hosted <img> tags inside article bodies point to URLs on your Zendesk subdomain (e.g., yourcompany.zendesk.com/hc/article_attachments/...). Copy that HTML into HubSpot and the images render — until you decommission the Zendesk account or Zendesk rotates auth tokens. Then every migrated article shows broken image placeholders.

Content blocks flattened. If your Zendesk Guide articles use content blocks (reusable snippets for legal notices, warranty text, or shared troubleshooting steps), the Help Center API flattens block content into inline text in the response. Writing that body back through any import method replaces the content-block references with plain text. If your team relies on reusable blocks, detect that before you export. (developer.zendesk.com)

Each of these failures is preventable, but only if you account for them before you start.

Data Mapping: Zendesk Guide vs. HubSpot Knowledge Base Structure

The two platforms use similar but non-identical hierarchies. The mapping looks simple on the surface but creates friction at the edges.

The nesting problem is the biggest structural mismatch. If your Zendesk Guide uses deeply nested sections (Section → Sub-Section → Sub-Sub-Section), you must flatten that hierarchy into HubSpot's two-level Category → Subcategory model. You have two choices: elevate the lowest-level section to a HubSpot Subcategory and discard the middle tiers, or use HubSpot tags to replicate the missing organizational layers. Plan this mapping on paper before you write a single line of code.

Method 1: HubSpot's Native Import Tool (Pros and Limits)

HubSpot offers two native paths: Smart copy from your live Zendesk Guide URL, or CSV import with mapped fields. Both are available on Service Hub Professional and Enterprise.

How Smart Copy Works

1. Navigate to Settings → Content → Knowledge Base → Import knowledge base.
2. Select Smart copy and enter your Zendesk Guide homepage URL.
3. HubSpot's crawler discovers articles, categories, and subcategories.
4. Review the preview, then import as drafts or publish directly.

What It Does Well

• Pulls article body HTML, titles, categories, and subcategories automatically.
• Supports imports from Zendesk, Freshdesk, Help Scout, and Intercom.
• No code required.

What It Breaks

• Tables: Not supported. The editor replaces them with a placeholder block. You get a CSV listing the affected articles.
• Custom styled divs: Stripped entirely. Callout boxes, accordions, or custom containers built with <div> styles lose their formatting.
• Side-by-side images: Forced into vertical layout. Any float or flexbox positioning is gone.
• Metadata: No original create date, no updated date, no author attribution. Every imported article gets the import timestamp and the importing user as author.
• Draft and restricted articles: Only publicly accessible articles are crawled. Zendesk drafts, internal-only articles, and content restricted by User Segments will not be discovered.

Method 2: Third-Party Tools and Custom API Scripts

When native tools fall short, you have two paths: visual migration platforms or custom scripts against both APIs.

Third-Party Migration Platforms

Help Desk Migration (Relokia) is the most established visual tool for Zendesk-to-HubSpot transfers. It uses a wizard interface to map Zendesk objects to HubSpot objects and handles tickets alongside Knowledge Base articles. Relokia advertises knowledge base features including inline image handling, multilingual content migration, and cross-link updating. (help-desk-migration.com)

The advantage is speed and reduced engineering effort. The disadvantage is limited control over edge cases: complex HTML formatting, deeply nested sections, and image URL rewriting may not be fully covered without custom configuration.

Custom API Scripts

For full control, build scripts that read from Zendesk's Help Center API and write to HubSpot's CMS API.

On the Zendesk side, the Incremental Article Export endpoint returns up to 1,000 articles per page using time-based pagination — each response includes a next_page URL with a new start_time equal to the end_time of the current page. Do not build your exporter around naive offset pagination if your help center is large; Zendesk limits offset pagination to 100 pages and recommends cursor pagination for larger data sets.

The catch: the incremental endpoint returns any article with any metadata change after the start time — not just content edits. Comment additions, label changes, or permission updates can push you past 1,000 articles per page quickly. Dedupe on article ID and store each response's end_time as your next checkpoint.

Zendesk API rate limits for the Help Center API vary by plan:

The Incremental Export endpoint has its own, stricter limit: 10 requests per minute (30 with the High Volume add-on). Your script must read the Retry-After header on 429 responses and implement exponential backoff.

On the HubSpot side, the POST /cms/v3/knowledge-base/articles endpoint has a practically tricky authentication requirement. Multiple developers report that Private App Tokens return a 401 "auth is missing" error on this endpoint, even when the correct scopes (cms.knowledge_base.articles.read, cms.knowledge_base.articles.write) are enabled. The endpoint often requires OAuth via a Public App — not a Private App — to function reliably. Your HubSpot account must also be on Service Hub Professional or Enterprise for the Knowledge Base API to be accessible.

A typical custom migration script follows this sequence:

# Pseudocode: Zendesk → HubSpot KB migration
for article in zendesk_incremental_export(start_time=0):
    html = article['body']
    
    # 1. Download and re-host inline images
    html = rewrite_image_urls(html, download_and_upload_to_hubspot)
    
    # 2. Flatten nested section → subcategory
    subcategory = map_section_to_subcategory(article['section_id'])
    
    # 3. Preserve metadata (workaround for HubSpot's missing fields)
    metadata_block = f"<!-- Original author: {article['author_id']} | Created: {article['created_at']} -->"
    
    # 4. POST to HubSpot KB API with OAuth token
    hubspot_create_article(
        title=article['title'],
        body=metadata_block + html,
        category=map_category(article['section_id']),
        subcategory=subcategory,
        keywords=article['label_names']
    )

At ClonePartner, we bypass the limitations of HubSpot's native crawler entirely. We use direct API integrations with custom rate-limit handling for both Zendesk's Incremental Export and HubSpot's CMS APIs to ensure zero data loss — preserving tables, custom HTML, and exact metadata like original author and create dates.

The Inline Image Trap: How to Prevent Broken Media

This is the single most common failure mode in knowledge base migrations, and it is entirely preventable.

Why Images Break

Zendesk Guide articles contain <img> tags with src attributes pointing to Zendesk-hosted URLs:

<img src="https://yourcompany.zendesk.com/hc/article_attachments/360012345678/screenshot.png">

When you copy this HTML into HubSpot, the image renders because the browser fetches it from Zendesk's server. This is a ticking time bomb:

• If you cancel your Zendesk account, those URLs return 404.
• Zendesk may rotate or expire attachment URLs.
• Some Zendesk configurations require authentication to access attachments, meaning images may already be invisible to unauthenticated visitors.
• Zendesk warns that unassociated article attachments may only be visible to signed-in users and can be purged if not associated to an article. (developer.zendesk.com)

The Fix: Programmatic Image Re-Hosting

The process is mechanical but cannot be skipped:

1. Parse every <img> tag in the article HTML.
2. Download the image binary from the Zendesk URL (authenticated, using your Zendesk API token).
3. Upload the image to HubSpot's File Manager (via the Files API) or your own CDN (S3, Cloudflare R2, etc.).
4. Rewrite the src attribute in the HTML to point to the new URL.
5. Verify — crawl the rewritten HTML and confirm every asset returns 200.
6. Import the modified HTML into HubSpot.

This must happen for every image, in every article, before import. On a 500-article knowledge base with an average of 3 images per article, that is 1,500 download-upload-rewrite cycles.

from bs4 import BeautifulSoup
 
def rewrite_media(html, asset_map):
    soup = BeautifulSoup(html, 'html.parser')
 
    for img in soup.select('img'):
        src = img.get('src')
        if src in asset_map:
            img['src'] = asset_map[src]
 
    for source in soup.select('source[srcset]'):
        srcset = source.get('srcset', '')
        source['srcset'] = ','.join(
            asset_map.get(part.strip().split(' ')[0], part.strip().split(' ')[0])
            for part in srcset.split(',')
        )
 
    for link in soup.select('a[href]'):
        href = link.get('href')
        if href in asset_map:
            link['href'] = asset_map[href]
 
    return str(soup)

Also rewrite internal article links during the same transform pass. If Zendesk articles link to other Zendesk article URLs, convert those links to the future HubSpot paths so readers and crawlers do not hit a redirect hop on every click.

At ClonePartner, image re-hosting is one of the steps we automate end-to-end — our scripts parse, download, re-host, and rewrite every media reference so zero images arrive broken in HubSpot.

Preserving SEO: Zendesk to HubSpot URL Redirects

If your Zendesk Guide articles rank in search or your product UI links directly to support articles, a migration without redirects will destroy that traffic. Build the redirect map before the first production import.

Zendesk Guide articles follow this URL pattern:

https://yourcompany.zendesk.com/hc/en-us/articles/123456789-Article-Title-Slug

HubSpot Knowledge Base articles default to:

https://knowledge.yourcompany.com/knowledge/article-slug

You need 301 redirects from every old Zendesk URL to its new HubSpot equivalent.

Where to Configure Redirects

The redirect location depends on your DNS and hosting setup:

• DNS/CDN level (Cloudflare, AWS CloudFront, or your web server) — the most reliable approach if your Zendesk subdomain was on a domain you control via host mapping.
• HubSpot's URL Redirect tool (Settings → Content → Domains & URLs → URL Redirects) — supports standard and flexible pattern redirects, defaults to 301 permanent. HubSpot currently limits each bulk CSV upload to 500 redirects, and URLs can be at most 140 characters. Propagation may take up to 48 hours. (knowledge.hubspot.com)
• Zendesk's Redirect Rules API — supports up to 50,000 redirect rules per brand, but redirects only fire for deleted articles that return a 404. Archived or unpublished articles will not trigger the redirect. Zendesk recommends the API over JavaScript redirects, which can hurt Google rankings. (support.zendesk.com)

The /knowledge/ Path Conflict

Redirect Mapping in Practice

Build a mapping table from your Zendesk article export:

Two rules:

• Prefer one-to-one 301s for article URLs that already rank.
• Use pattern redirects only when the slug logic is genuinely predictable.

Upload this as a bulk redirect in HubSpot or implement it as a CDN rule. Large help centers with locale-specific URLs often need multiple redirect batches plus spot checks on the longest URLs. At ClonePartner, we auto-generate this mapping from the Zendesk export and HubSpot import data, ensuring every article gets a redirect rule without manual work.

Post-Migration QA Checklist

After import, run these checks before publishing any articles or updating DNS. For a full 20-point validation process, see Post-Migration QA: 20 Tests to Run After Your Helpdesk Migration.

• Article count match. Compare published article counts in Zendesk vs. HubSpot, broken down by locale, draft/published state, and top-level category. This catches missed translations and over-400 batch issues fast.
• Formatting spot-check. Open 10–15 articles that originally contained tables, code blocks, callout boxes, or custom HTML. Verify rendering in HubSpot's editor and on the live preview.
• Image rendering. Check at least 20 articles with inline images. Open browser dev tools and confirm every <img> tag loads from your new host (HubSpot File Manager or CDN), not from *.zendesk.com. Test in incognito mode to avoid cached Zendesk sessions.
• Internal links. Search the imported HTML for any remaining links pointing to yourcompany.zendesk.com/hc/.... These must be rewritten to HubSpot Knowledge Base URLs.
• Category and subcategory structure. Walk the full category tree in HubSpot and verify it matches your planned mapping document.
• Search functionality. Use HubSpot's Knowledge Base search or the Site Search API with type=KNOWLEDGE_ARTICLE to confirm imported articles are indexing correctly.
• Redirect validation. Test 10+ old Zendesk URLs in incognito. Confirm each returns a 301 to the correct HubSpot article. Verify with curl -I. Do not accept 302s, redirect chains, or locale mismatches.
• Metadata audit. If you embedded original timestamps as HTML comments or custom properties via the API, verify they are present and accurate on a sample set.
• Multi-language articles. If your Zendesk Guide served multiple locales, confirm each language variant landed in the correct HubSpot knowledge base or language group.
• Access controls. If any articles were restricted to specific user segments in Zendesk, verify the equivalent access rules are configured in HubSpot. Permission bugs do not surface in anonymous smoke tests.

Before preparing your HubSpot environment for the import, review the HubSpot Service Hub Migration Checklist to make sure pipelines, properties, and user permissions are configured correctly.

Choosing the Right Migration Approach

The right method depends on your article count, formatting complexity, and tolerance for post-import cleanup.

If your knowledge base is small, text-heavy, and you can afford a few hours of manual cleanup — use the native tool. If you have hundreds of articles with tables, inline images, content blocks, or SEO traffic at stake, a custom API approach (or a team that has done this before) is the only path that avoids silent data loss.

At ClonePartner, we build custom migration scripts that handle image re-hosting, HTML sanitization, metadata preservation, and SEO redirect generation as a single pipeline. The technical challenges are the same whether you have 50 articles or 5,000+ — the difference is how much you catch before go-live.