How to Migrate Your FAQ from Zendesk (Step-by-Step)

Why Teams Migrate from Zendesk

Zendesk is a powerful help desk. But for teams that primarily need FAQ and knowledge base functionality, it comes with baggage:

Per-agent pricing — $55-115/agent/month for features you may not use
No API-first approach — FAQ content is locked behind Zendesk's rendering
Widget limitations — the Zendesk Web Widget follows Zendesk's design, not yours
Complexity — Zendesk is a full CRM/ticketing suite when you just need FAQ management

If you've outgrown Zendesk for FAQ (or never needed the full suite), migrating to an API-first FAQ platform is straightforward. Here's how.

Before You Start

Audit Your Zendesk Content

Before exporting, take stock of what you have:

Count your articles — How many FAQ articles are in Zendesk Guide?
Check categories/sections — Note your organizational structure
Identify attachments — Images, PDFs, and files embedded in articles
Review translations — If using Zendesk's multi-language feature, note which locales are active
Check article status — Draft vs. published, internal vs. public

Map Your Content Structure

Zendesk Guide organizes content as: Category → Section → Article

TheFAQApp uses: Collection → FAQ (question + answer)

The mapping is simple:

Zendesk	TheFAQApp
Category	Collection group (optional)
Section	Collection
Article title	Question
Article body	Answer
Labels	Tags

Step 1: Export from Zendesk

Option A: Zendesk API Export (Recommended)

The Zendesk API gives you full access to your content with metadata:

# List all articles
curl https://your-subdomain.zendesk.com/api/v2/help_center/articles.json \
  -u your-email@company.com/token:YOUR_ZENDESK_API_TOKEN

# Export a specific article
curl https://your-subdomain.zendesk.com/api/v2/help_center/articles/{id}.json \
  -u your-email@company.com/token:YOUR_ZENDESK_API_TOKEN

The response includes title, body (HTML), section_id, label_names, locale, and draft status.

Option B: CSV Export

From the Zendesk Admin panel:

Go to Guide Admin → Settings
Click Export articles to CSV
Download the CSV file

The CSV includes article titles, bodies, sections, and metadata. This works for smaller knowledge bases.

Option C: Google Takeout (if you're desperate)

Zendesk supports Google Takeout for data export, but the format is less structured. Use the API export instead.

Step 2: Transform Your Content

Zendesk articles are HTML. TheFAQApp accepts HTML in answer fields, so minimal transformation is needed. However, you'll want to:

Clean Up HTML

Zendesk articles often contain inline styles and Zendesk-specific CSS classes:

// Simple cleanup script
function cleanZendeskHTML(html) {
  return html
    // Remove Zendesk-specific classes
    .replace(/class="[^"]*"/g, '')
    // Remove inline styles
    .replace(/style="[^"]*"/g, '')
    // Fix relative image URLs
    .replace(
      /src="\/hc\/article_attachments/g,
      'src="https://your-subdomain.zendesk.com/hc/article_attachments'
    );
}

Map Sections to Collections

Create a mapping file from your Zendesk sections to TheFAQApp collections:

{
  "section_mappings": {
    "360001234567": "getting-started",
    "360001234568": "billing",
    "360001234569": "api-reference",
    "360001234570": "troubleshooting"
  }
}

Handle Images

If your articles contain images hosted on Zendesk:

Download all images from Zendesk's article attachments API
Upload to your hosting (S3, Cloudflare R2, Vercel Blob, etc.)
Update image URLs in the article HTML

Step 3: Import into TheFAQApp

Using the API (Recommended)

Create collections first, then import FAQs:

# Create a collection
curl -X POST https://www.thefaq.app/api/v1/your-org/collections \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Getting Started",
    "slug": "getting-started",
    "description": "Help articles for new users"
  }'

# Import a FAQ
curl -X POST https://www.thefaq.app/api/v1/your-org/faqs \
  -H "Authorization: Bearer your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "question": "How do I reset my password?",
    "answer": "<p>Go to Settings > Security > Reset Password...</p>",
    "collectionSlug": "getting-started",
    "tags": ["account", "security"],
    "locale": "en"
  }'

Bulk Import Script

For larger migrations, use the SDK:

import { FAQClient } from '@faqapp/core';
import fs from 'fs';

const client = new FAQClient({
  apiKey: process.env.FAQ_API_KEY,
  organizationSlug: 'your-org',
});

// Load your transformed Zendesk export
const articles = JSON.parse(fs.readFileSync('zendesk-export.json', 'utf-8'));
const sectionMap = JSON.parse(fs.readFileSync('section-mappings.json', 'utf-8'));

// Create collections first
const collections = new Set(Object.values(sectionMap.section_mappings));
for (const slug of collections) {
  await client.collections.create({ name: slug, slug });
}

// Import FAQs
for (const article of articles) {
  await client.faqs.create({
    question: article.title,
    answer: cleanZendeskHTML(article.body),
    collectionSlug: sectionMap.section_mappings[article.section_id],
    tags: article.label_names,
    locale: article.locale,
  });

  // Respect rate limits
  await new Promise(r => setTimeout(r, 100));
}

console.log(`Imported ${articles.length} FAQs`);

Step 4: Verify and Test

After import, verify your content:

Spot-check 10-20 FAQs — Compare with Zendesk to ensure content integrity
Check formatting — HTML rendering, images loading, links working
Verify categories — FAQs in the right collections
Test search — Search for common queries and confirm results
Check translations — If you imported multi-language content, verify locale switching

Step 5: Update Your Integration Points

Replace Zendesk Web Widget

If you're using the Zendesk Web Widget for FAQ, replace it with the TheFAQApp widget or a custom implementation:

<!-- Remove Zendesk widget -->
<!-- <script id="ze-snippet" src="https://static.zdassets.com/ekr/snippet.js?key=..."></script> -->

<!-- Add TheFAQApp widget (if using the widget) -->
<script src="https://widget.thefaq.app/v1/widget.js" data-org="your-org"></script>

<!-- Or build your own with the API -->

For a custom approach, see how to embed a FAQ widget anywhere.

Update DNS / Redirects

If you were using support.yourcompany.com → Zendesk Guide, set up redirects:

Point support.yourcompany.com → your new FAQ page
Or use TheFAQApp's custom domain feature for hosted FAQ pages

Update Internal Links

Search your codebase and documentation for links to your Zendesk help center and update them to point to your new FAQ page.

Step 6: Run in Parallel (Optional)

For zero-downtime migration:

Week 1 — Import all content to TheFAQApp. Keep Zendesk live.
Week 2 — Set up your new FAQ page/widget. Test with internal users.
Week 3 — Switch public traffic to the new FAQ. Keep Zendesk as read-only backup.
Week 4 — Confirm search analytics and deflection metrics look healthy. Decommission Zendesk Guide.

What You Gain After Migration

After migrating from Zendesk to an API-first FAQ platform:

Cost savings — No more per-agent pricing for FAQ management. See how to calculate FAQ ROI.
API access — Your FAQ content is now available via REST API for any integration
Custom rendering — Build your FAQ page with your own design system
Better search — API-powered search with analytics
AI features — Generate FAQ content from support tickets
Developer experience — TypeScript SDK, Next.js integration, programmatic management

Getting Started

Ready to migrate? Here's the fastest path:

Sign up for free — no credit card required
Export from Zendesk using the API (Step 1 above)
Import via TheFAQApp API — the free tier supports up to 50 FAQs
Test and verify — spot-check your content
Switch over — update your widget and DNS

The entire process takes 1-2 hours for most knowledge bases. For larger migrations (500+ articles), budget half a day.

Start your migration →