Migrating existing content to your help center

<div class="article-banners">
<div id="docs-wmp-link"><a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" rel="noopener" target="_blank">What's my plan?</a></div>
<div class="article-banner" id="suite_all">
<table>
<tbody>
<tr>
<td>
<strong>All Suites</strong>
</td>
<td>Team, Growth, Professional, Enterprise, or Enterprise Plus</td>
</tr>
</tbody>
</table>
</div>
<div class="article-banner" id="support_with_guide_all">
<table>
<tbody>
<tr>
<td>
<strong>Support with</strong>
</td>
<td>Knowledge Professional or Enterprise</td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="body">
<p class="p">There are many ways to migrate content from one help center to another. This article primarily
focuses on using your help center API to programmatically import content, and gives a
high-level overview of the process of migrating existing content to your new help
center. You can also migrate content using the following approaches:</p>
<ul class="ul" id="zug_hc_migrating_existing_content_to_your_help_center__ul_evf_j2h_bpb">
<li class="li">
<strong class="ph b">Copying and pasting</strong>: If you are only migrating a few articles, then the
fastest and easiest way is to simply copy and paste content from your previous help
center into a new article.</li>
<li class="li">
<strong class="ph b">Professional services</strong>: If you have large or complex migrations, you can <a class="xref" href="https://www.zendesk.com/customer-experience/professional-services/" target="_blank">hire Zendesk to help</a> you with your
migration.</li>
<li class="li">
<strong class="ph b">Partner apps</strong>: You can explore the Zendesk <a class="xref" href="https://www.zendesk.com/apps/" target="_blank">apps
marketplace</a> to find partner apps such as <a class="xref" href="https://www.zendesk.com/marketplace/apps/support/120364/import--help-desk-migration" target="_blank">Help Desk Migration</a>.</li>
</ul>
<p class="p">This article covers the following topics:</p>
<ul class="ul" id="zug_hc_migrating_existing_content_to_your_help_center__ul_fvf_j2h_bpb">
<li class="li">
<a class="xref" href="#topic_rtq_kdh_bpb">Migrating content to your knowledge base</a><ul class="ul" id="zug_hc_migrating_existing_content_to_your_help_center__ul_gvf_j2h_bpb">
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_gzl_t2h_bpb">Importing your authors as Zendesk users</a></li>
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_wfq_s2h_bpb">Creating categories in your knowledge base</a></li>
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_gtz_r2h_bpb">Creating user segments (optional)</a></li>
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_cxv_r2h_bpb">Creating sections in your categories</a></li>
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_t5q_r2h_bpb">Creating articles in your sections</a></li>
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_hzl_r2h_bpb">Uploading attachments (if necessary)</a></li>
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_wbh_r2h_bpb">Importing article comments</a></li>
</ul>
</li>
<li class="li">
<a class="xref" href="#topic_uvz_kdh_bpb">Migrating content to your community</a><ul class="ul" id="zug_hc_migrating_existing_content_to_your_help_center__ul_hvf_j2h_bpb">
<li class="li"><a class="xref" href="#topic_rtq_kdh_bpb__section_gtz_r2h_bpb">Creating user segments (optional)</a></li>
<li class="li"><a class="xref" href="#topic_uvz_kdh_bpb__section_pwh_tdh_bpb">Importing topics in your community</a></li>
<li class="li"><a class="xref" href="#topic_uvz_kdh_bpb__section_qfv_xdh_bpb">Importing posts in topics</a></li>
<li class="li"><a class="xref" href="#topic_uvz_kdh_bpb__section_y41_tdh_bpb">Importing comments in posts</a></li>
</ul>
</li>
</ul>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_rtq_kdh_bpb">
<h2 class="title topictitle2" id="ariaid-title2">Migrating content to your knowledge base</h2>
<div class="body">
<p class="p">Migrating content from an external system into your help center is a multi-step
process where data from one step is required for subsequent steps.</p>
<p class="p">Planning is critical. You'll need to map the structure of your legacy content to your
help center's three-layer structure:</p>
<p class="p"><img class="image img-screenshot" id="topic_rtq_kdh_bpb__image_dzt_s2h_bpb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/hc_knowledge_base.png" width="300"></p>
<div class="section" id="topic_rtq_kdh_bpb__section_gzl_t2h_bpb">
<h3 class="title sectiontitle">Importing your authors as Zendesk users</h3>
<p class="p">First, you must import the authors of all your articles as
Zendesk users with the role of "agent" (an agent in Zendesk is not necessarily
someone who solves tickets (see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408883763866" target="_blank">Understanding Zendesk Support user
roles</a>).</p>
<p class="p">To create Zendesk users with the API (see <a class="xref" href="https://developer.zendesk.com/api-reference/ticketing/users/users/#create-user" target="_blank">Create user</a>). Ensure you set the
<code class="ph codeph">role</code> attribute to "agent" in each POST request.</p>
<div class="p">After
you have successfully created a user, Zendesk returns the details of the user in
the JSON response, including the user's new
ID:<pre class="pre codeblock"><code>{
"user": {
"id": 9873843,
"name": "Roger Wilco",
...
}
}</code></pre>
</div>
<p class="p">Record
the ID of each user as you'll need the IDs to set the <code class="ph codeph">author_id</code>
attribute of each article you create in your help center.</p>
Tip: You might
want to create a map of each author ID and their legacy articles. <p class="p">If you plan on
using <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408886146842" target="_blank">organizations</a> in <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408837707290" target="_blank">user segments</a> to segregate sections,
you must create the organizations <em class="ph i">before</em> you create any users. You can
then assign the organization ID to the user when you are creating the user (see
<a class="xref" href="https://developer.zendesk.com/rest_api/docs/core/organizations#create-organization" target="_blank">Create organization</a>). If your users
will belong to multiple organizations, then use <a class="xref" href="https://developer.zendesk.com/rest_api/docs/core/organization_memberships" target="_blank">organization memberships</a> to add
organizations to the user record.</p>
</div>
<div class="section" id="topic_rtq_kdh_bpb__section_wfq_s2h_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Creating categories in your knowledge base</strong></h3>
<div class="p">Categories are collections of sections (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/categories#create-category" target="_blank">Create category</a>). After you have
created a category, Zendesk returns a JSON response with the category's new
ID:<pre class="pre codeblock"><code>{
"category": {
"id": 37486578,
"name": "Super Hero Tricks",
"description": "This category contains a collection of Super Hero tricks",
"locale": "en-us",
"position": 2,
...
}
}</code></pre>
</div>
<p class="p">Record the ID of each category, because when you create sections later, you'll
need the IDs to assign sections to specific categories.</p>
</div>
<div class="section" id="topic_rtq_kdh_bpb__section_gtz_r2h_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Creating user segments (optional)</strong></h3>
<p class="p">If you want to restrict access to certain sections in your help center, you can
assign <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408837707290" target="_blank">user
segments</a> to your sections (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/user_segments#create-user-segment" target="_blank">Create user segment</a>).</p>
<div class="p">After you have created a user segment, Zendesk returns a JSON response with the
user segment's new
ID:<pre class="pre codeblock"><code>{
"user_segment": {
"id": 7284
"name": "VIP agents",
"user_type": "staff",
"group_ids": [12, ...],
"organization_ids": [42, ...],
"tags": ["vip"],
"created_at": "2017-05-21T20:01:12Z",
"updated_at": "2017-05-21T20:01:12Z",
"built_in": false
}
}</code></pre>
</div>
<p class="p">Record the ID of each user segment because when you are creating sections later,
you'll need the segment ID to assign access restrictions to the sections.</p>
</div>
<div class="section" id="topic_rtq_kdh_bpb__section_cxv_r2h_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Creating sections in your categories</strong></h3>
<div class="p">Sections are collections of articles (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/sections#create-section" target="_blank">Create section</a>). Ensure you set the
<code class="ph codeph">category_id</code> and <code class="ph codeph">user_segment_id</code> (if any),
in each POST request. Zendesk returns a JSON response with the section's new
ID:<pre class="pre codeblock"><code>{
"section": {
"id": 3457836,
"name": "Avionics",
"description": "This section contains articles on flight instruments",
"locale": "en-us",
"category_id": 3465,
...
}
}</code></pre>
</div>
<p class="p">Record the ID of each section because when you create articles later, you'll need
the section IDs to assign articles to specific sections.</p>
</div>
<div class="section" id="topic_rtq_kdh_bpb__section_t5q_r2h_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Creating articles in your sections</strong></h3>
<div class="p">When you have all the section IDs and user IDs from the previous steps, you can
create articles (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/articles#create-article" target="_blank">Create article</a>). In addition to the
<code class="ph codeph">title</code> and <code class="ph codeph">body</code>, make sure you set the
<code class="ph codeph">author_id</code> and <code class="ph codeph">section_id</code> in each POST
request.<div class="note">
<span class="notetitle">Note:</span> All authors are automatically subscribed to their articles. If
your help center has been activated, then the authors will receive an email
notification when the article is created.</div>
</div>
<div class="p">Zendesk returns a JSON response that looks as
follows:<pre class="pre codeblock"><code>{
"article": {
"id": 37486578,
"author_id": 3465,
"promoted": false,
"position": 42,
"comments_disabled": true,
"section_id": 98838,
...
}
}</code></pre>
</div>
</div>
<div class="section" id="topic_rtq_kdh_bpb__section_hzl_r2h_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Uploading attachments (if necessary)</strong></h3>
<p class="p">If an article has inline images that aren't hosted on a public file server, such
as Amazon S3, then upload the images to your help center (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/article_attachments#create-unassociated-attachment" target="_blank">Create unassociated attachment</a>).
Ensure you set the <code class="ph codeph">inline</code> parameter to
<code class="ph codeph">true</code>.</p>
<div class="p">Zendesk returns a JSON response with a URL (<code class="ph codeph">content_url</code>) for the
attachment:<pre class="pre codeblock"><code>{
"article_attachment": {
"id": 1428,
"article_id": null,
"file_name": "icon.jpg",
"content_url": "https://company.zendesk.com/hc/article_attachments/1428/icon.jpg",
"content_type": "application/image",
"size": 58298,
"inline": true
}
}</code></pre>
</div>
<p class="p">Use the <code class="ph codeph">content_url</code> to update the image URL in the HTML of the
article (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/articles#associate-attachments-in-bulk-to-article" target="_blank">Associate attachments in bulk to
article</a>).</p>
</div>
<div class="section" id="topic_rtq_kdh_bpb__section_wbh_r2h_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Importing article comments</strong></h3>
<div class="p">To import comments, you'll need an author ID and the article's ID. Both agents
and end users can be authors of comments (see <a class="xref" href="https://developer.zendesk.com/api-reference/help_center/help-center-api/post_comments/#create-post-comment" target="_blank">Create comment</a>).<div class="note">
<span class="notetitle">Note:</span> A comment author
is automatically subscribed to the article. If your help center has been
activated, then they'll get an email notification when their comment is
created. </div>
</div>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_uvz_kdh_bpb">
<h2 class="title topictitle2" id="ariaid-title3">Migrating content to your community</h2>
<div class="body">
<p class="p">Importing community content has many of the same considerations as importing a
knowledge base. You'll need to <a class="xref" href="https://developer.zendesk.com/rest_api/docs/core/users#create-user" target="_blank">import users</a> to assign authors to posts.
You'll also need to map the structure of your legacy community content to the
two-layer structure of your help center community:</p>
<p class="p"><img class="image img-screenshot" id="topic_uvz_kdh_bpb__image_lck_qdh_bpb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/hc_community.png" width="300"></p>
<div class="section" id="topic_uvz_kdh_bpb__section_bgp_tdh_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Creating user segments (optional)</strong></h3>
<p class="p">If you want to restrict access to certain topics, you'll need user segment IDs
(see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/user_segments#create-user-segment" target="_blank">Create a user segment</a>). When creating
the topics later, you'll need the user segment IDs to assign access restrictions
to topics.</p>
</div>
<div class="section" id="topic_uvz_kdh_bpb__section_pwh_tdh_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Importing topics in your community</strong></h3>
<p class="p">If applicable, ensure you set the <code class="ph codeph">user_segment_id</code> in the POST
request (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/topics#create-topic" target="_blank">Create topic</a>).</p>
<p class="p">Zendesk returns a JSON response with the topic ID:</p>
<pre class="pre codeblock"><code>{
"topic": {
"id": 115000553548,
"name": "Help Center-Tricks",
...
}
}</code></pre>
<p class="p">Record the ID of each topic because when you create topics later, you'll need the
topic IDs to assign posts to specific topics.</p>
</div>
<div class="section" id="topic_uvz_kdh_bpb__section_qfv_xdh_bpb">
<h3 class="title sectiontitle">Importing posts in topics</h3>
<p class="p">In addition
to the <code class="ph codeph">title</code> and <code class="ph codeph">details</code>, make sure you set
the <code class="ph codeph">author_id</code> and <code class="ph codeph">topic_id</code> in each POST
request (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/posts#create-post" target="_blank">Create post</a>).</p>
<p class="p">Unlike KB
articles, authors of community posts can be agents or end users.</p>
<p class="p">When
creating a post, the author is automatically subscribed to all updates to that
topic, and will be notified when a new post is created or updated.</p>
<p class="p">All
subscribers of the same topic receive an email notification when the post is
created. To prevent subscribers from being overwhelmed by notifications when
bulk importing posts, include a <code class="ph codeph">notify_subscribers</code> parameter
with a value of <code class="ph codeph">false</code> in your POST
requests.</p>
<pre class="pre codeblock"><code>{
"post": {
"id": 35467,
"author_id": 89567,
"title": "Help!",
"details": "My printer is on fire!",
"notify_subscribers": false,
...
}
}</code></pre>
</div>
<div class="section" id="topic_uvz_kdh_bpb__section_y41_tdh_bpb">
<h3 class="title sectiontitle"><strong class="ph b">Importing comments in posts</strong></h3>
<p class="p">After creating the posts and getting their IDs, you can now add their associated
comments (see <a class="xref" href="https://developer.zendesk.com/rest_api/docs/help_center/post_comments#create-comment" target="_blank">Create comment</a>).</p>
<p class="p">You can only create one comment at a time. When creating a post comment, the
author of the comment is automatically subscribed to all updates to that topic
and are notified when a new post is created or updated.</p>
<p class="p">All subscribers of the same topic receive an email notification when the comment
is created. To prevent subscribers from being overwhelmed by notifications,
include a <code class="ph codeph">notify_subscribers</code> parameter with a value of
<code class="ph codeph">false</code> in your POST requests.</p>
</div>
</div>
</div>
<script id="docs-schema-markup" type="application/ld+json">{
"@context": "https://schema.org",
"@type": "TechArticle",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408828053146",
"url": "https://support.zendesk.com/hc/en-us/articles/4408828053146-Migrating-existing-content-to-your-help-center",
"headline": "Migrating existing content to your help center",
"description": "You can migrate existing help center content by programmatically importing authors, categories, sections, articles, attachments, comments, and community posts using the help center API while mapping legacy content structure to the new system.",
"articleSection": "Setting up your help center",
"datePublished": "2021-10-16T03:31:55+00:00",
"dateModified": "2026-03-30T05:47:38+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408828053146"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk",
"@id": "https://www.zendesk.com"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"@id": "https://support.zendesk.com/hc/"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk",
"@id": "https://www.zendesk.com",
"softwareAddOn": {
"@type": "SoftwareApplication",
"name": "Knowledge",
"@id": "https://support.zendesk.com/hc/en-us/sections/4405298860954"
}
}
}</script>