How to Migrate Your FAQ from Help Scout to an API-First Platform

Why Teams Move Away from Help Scout Docs

Help Scout is a solid help desk with a clean UI. But Help Scout Docs — their knowledge base product — has real limitations for teams that want more from their FAQ:

No API-first approach — Help Scout Docs is designed to serve content through their Beacon widget or hosted Docs site. You can't easily consume FAQ content in your own app via API.
Limited customization — Docs styling is constrained to Help Scout's theme editor. Deep custom layouts and branded experiences require workarounds.
Bundled pricing — Help Scout starts at $50/user/month. If you mainly need FAQ management, you're paying for shared inbox, live chat, and more.
No headless option — You can't decouple the content layer from the rendering layer. If you want FAQ content in a mobile app, internal tool, or custom frontend, Help Scout doesn't support that natively.
Basic analytics — Help Scout Docs provides article views and ratings, but lacks search analytics, click-through tracking, and the data you need to optimize FAQ content.

If you need an API-first FAQ platform with full developer control, migrating from Help Scout is straightforward.

Before You Start

Audit Your Help Scout Docs

Take inventory of your Help Scout knowledge base:

Count articles — How many published articles across all collections?
Check collections and categories — Note your organizational structure
Identify assets — Images and files embedded in articles
Review article status — Published vs. draft
Note custom redirects — Any redirect rules set up in Help Scout Docs

Map Your Content Structure

Help Scout Docs organizes content as: Collection → Category → Article

TheFAQApp uses: Collection → FAQ (question + answer)

Help Scout Docs	TheFAQApp
Collection	Collection group (optional)
Category	Collection
Article name	Question
Article body	Answer
Tags	Tags

Step 1: Export from Help Scout

Option A: Help Scout Docs API (Recommended)

Help Scout has a well-documented API for Docs. You'll need an API key from Your Profile → API Keys in the Help Scout dashboard.

# List all collections
curl https://docsapi.helpscout.net/v1/collections \
  -u "YOUR_API_KEY:X"

# List all articles in a collection
curl https://docsapi.helpscout.net/v1/collections/{collectionId}/articles \
  -u "YOUR_API_KEY:X"

# Get a specific article with full content
curl https://docsapi.helpscout.net/v1/articles/{articleId} \
  -u "YOUR_API_KEY:X"

The article response includes name (title), text (HTML body), categories, status (published/not published), and keywords.

Full export script:

async function exportHelpScoutDocs(apiKey) {
  const headers = {
    'Authorization': `Basic ${btoa(apiKey + ':X')}`,
  };

  // Get all collections
  const collectionsRes = await fetch(
    'https://docsapi.helpscout.net/v1/collections',
    { headers }
  );
  const collections = (await collectionsRes.json()).collections.items;

  const allArticles = [];

  for (const collection of collections) {
    // Get articles in each collection
    let page = 1;
    let hasMore = true;

    while (hasMore) {
      const res = await fetch(
        `https://docsapi.helpscout.net/v1/collections/${collection.id}/articles?page=${page}`,
        { headers }
      );
      const data = await res.json();

      for (const article of data.articles.items) {
        // Fetch full article content
        const fullRes = await fetch(
          `https://docsapi.helpscout.net/v1/articles/${article.id}`,
          { headers }
        );
        const full = (await fullRes.json()).article;

        allArticles.push({
          ...full,
          collectionId: collection.id,
          collectionName: collection.name,
        });

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

      hasMore = page < data.articles.pages;
      page++;
    }
  }

  return { collections, articles: allArticles };
}

Option B: Manual Copy

For very small knowledge bases (under 20 articles), you can copy-paste content directly. But the API export preserves metadata and formatting much better.

Step 2: Transform Your Content

Help Scout Docs articles are HTML. TheFAQApp accepts HTML in answers, so most content transfers directly. Clean up Help Scout-specific elements:

function cleanHelpScoutHTML(html) {
  return html
    // Remove Help Scout tracking attributes
    .replace(/data-hs-[^=]*="[^"]*"/g, '')
    // Remove inline styles from Help Scout editor
    .replace(/style="[^"]*"/g, '')
    // Fix relative image URLs to absolute
    .replace(
      /src="(\/docs\/assets\/[^"]+)"/g,
      'src="https://your-docs.helpscoutdocs.com$1"'
    );
}

Map Categories to Collections

Create a mapping from Help Scout categories to TheFAQApp collections:

{
  "category_mappings": {
    "category-id-1": "getting-started",
    "category-id-2": "billing",
    "category-id-3": "integrations",
    "category-id-4": "troubleshooting"
  }
}

Handle Images

Help Scout hosts images on their CDN. Download and re-host them:

Extract image URLs from article HTML
Download from Help Scout's CDN
Upload to your hosting (S3, Cloudflare R2, Vercel Blob)
Replace URLs in article HTML

Step 3: Import into TheFAQApp

Using the API

Create collections, 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": "Onboarding and setup articles"
  }'

# 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 set up email forwarding?",
    "answer": "<p>Navigate to Settings > Email Forwarding...</p>",
    "collectionSlug": "getting-started",
    "tags": ["email", "setup"]
  }'

Bulk Import Script

For larger knowledge bases, 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 export data
const { articles } = JSON.parse(
  fs.readFileSync('helpscout-export.json', 'utf-8')
);
const categoryMap = JSON.parse(
  fs.readFileSync('category-mappings.json', 'utf-8')
);

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

// Import articles as FAQs
let imported = 0;
for (const article of articles) {
  if (article.status !== 'published') continue;

  const categoryId = article.categories?.[0]?.id;
  const collectionSlug = categoryMap.category_mappings[categoryId] || 'general';

  await client.faqs.create({
    question: article.name,
    answer: cleanHelpScoutHTML(article.text),
    collectionSlug,
    tags: article.keywords || [],
  });

  imported++;
  await new Promise(r => setTimeout(r, 100));
}

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

Step 4: Verify and Test

After import:

Spot-check FAQs — Compare 10-20 items against Help Scout originals
Check formatting — Verify HTML renders correctly, images load, links work
Verify collections — Confirm FAQs landed in the right collections
Test search — Search common queries and verify results
Check SEO — Ensure FAQ page titles and descriptions are set for search visibility

Step 5: Replace Help Scout Docs

Replace Beacon with TheFAQApp Widget

If you use Help Scout's Beacon widget for FAQ access:

<!-- Remove Help Scout Beacon -->
<!-- <script>!function(e,t,n){...}(window,document,"Beacon");</script> -->

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

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

Update Your Docs URL

If you used Help Scout's hosted Docs site (e.g., docs.yourcompany.com):

Point the domain to your new TheFAQApp hosted page
Or build a custom FAQ page with the API
Set up 301 redirects from old article URLs to new FAQ URLs

Keep Help Scout for Ticketing

Like many teams, you might want to keep Help Scout for email support while moving FAQ to a dedicated platform:

Help Scout → shared inbox, customer conversations
TheFAQApp → FAQ content, knowledge base, self-service portal

This lets you reduce support tickets by improving self-service while keeping your existing support workflow.

Step 6: Run in Parallel

For a safe migration:

Week 1 — Import content to TheFAQApp. Keep Help Scout Docs live.
Week 2 — Deploy your new FAQ page. Test internally.
Week 3 — Switch traffic. Monitor FAQ effectiveness metrics.
Week 4 — Verify everything works. Disable Help Scout Docs if no longer needed.

What You Gain After Migration

Cost savings — Dedicated FAQ management without per-seat help desk pricing. See how to calculate FAQ ROI.
API access — Consume your FAQ content anywhere via REST API
Custom rendering — Full control over FAQ page design and layout
Better search — API-powered search with analytics
AI features — Auto-generate FAQ content from support data
Developer experience — TypeScript SDK, Next.js integration, programmatic management

Getting Started

Ready to migrate from Help Scout? Here's the fastest path:

Sign up for free — no credit card required
Export from Help Scout using the Docs 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 Beacon and Docs URL

Most knowledge bases migrate in under 2 hours.

Start your migration →