Bulk importing organization data with the data importer

<body>
<p id="docs-hc-snippet" style="display: none;">Rather than add organizations one at a time, you can bulk add several organizations at once by importing a CSV (comma-separated values) file. You can use bulk import to add organizations or update organizations. You must be an administrator to bulk import organizations. You can also add or updatemultiple usersandmultiple custom object recordsat once.</p>
<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_all">
<table>
<tbody>
<tr>
<td>
<strong>Support</strong>
</td>
<td>Team, Professional, or Enterprise</td>
</tr>
</tbody>
</table>
</div>

</div>
<div id="docs-ai-summary">
<p id="docs-ai-summary-toggle">Summary: <span id="up-triangle">◀</span><span id="down-triangle">▼</span></p>
<p id="docs-ai-summary-content">You can bulk import or update multiple organizations at once using a CSV file, saving time compared to adding them individually. The CSV must follow specific formatting rules and size limits, and you must be an admin to perform imports. The process supports core organization data and custom fields, but some data requires API use. Importing is queued and irreversible, so testing with a single record first is recommended.</p>
</div>

<div class="body">

<p class="p">Rather than add organizations one at a time, you can bulk add several organizations at once by
importing a CSV (comma-separated values) file. You can use bulk import to add organizations or
update organizations. You must be an administrator to bulk import organizations. You can also
add or update <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408893496218" target="_blank">multiple users</a> and <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/6100391508250" target="_blank">multiple custom object records</a> at once.</p>
<p class="p">If you would like to bulk import both organizations and users, you must bulk import
organizations first. For information on bulk importing users, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408893496218" target="_blank">Bulk importing users</a></p>
<p class="p">Bulk importing organizations can't be undone. Before importing the CSV file that contains the
information of all your organizations, test that same CSV file with a single organization
record to make sure the upload works as intended. </p>
<p class="p">If you're using the legacy method to import organization data through the Bulk actions pages,
see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/10729670046106" target="_blank">Bulk importing organization data (legacy)</a>.</p>
<div class="p">This article includes the following topics:<ul class="ul" id="topic_a1x_vrk_yz__ul_lnr_3bt_ffc">
<li class="li"><a class="xref" href="#id_og5_3ct_ffc">Limitations for bulk importing with the data
importer</a></li>
<li class="li"><a class="xref" href="#topic_ltw_lbt_ffc">Creating the CSV organization data file</a></li>
<li class="li"><a class="xref" href="#topic_hvl_mbt_ffc">Importing organizations with the data importer</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="id_og5_3ct_ffc">
<h2 class="title topictitle2" id="ariaid-title2">Limitations for bulk importing with the data importer</h2>
<div class="body">
<p class="p">You can import a core set of data about users and organizations. To import data not listed
in the table below, you must use the Zendesk REST API instead. See <a class="xref" href="https://developer.zendesk.com/rest_api/docs/core/users" target="_blank">Importing
users with the Zendesk API</a>.</p>
<ul class="ul" id="id_og5_3ct_ffc__d8e28">
<li class="li">When using the data importer, the import CSV file can't exceed 1 GB in size. We
recommend a maximum of 500,000 rows. That is one header row and up to 499,999 rows of
data. Furthermore, each row can't exceed 128 KB in size.</li>
<li class="li">The import CSV file can contain a maximum of 200 columns.</li>
<li class="li">The import CSV file can't guarantee import order for rows.</li>
<li class="li">Don't include the same user or organization more than once within a CSV file. Doing so
can cause your import to fail.</li>
<li class="li">There's no guarantee that records are created or updated in the order they appear in the
CSV file.</li>
<li class="li">You can only import one CSV file at a time. Therefore, if you have more data than the
maximum number of rows supported for the CSV file, you must create separate files for each
batch and import them one after another. When you're not using the data importer, up to
two batches are queued and run in the background. If you want to import more than two
batches, you need to wait until the first batches are finished importing to add more.</li>
<li class="li">You cannot use the bulk importer to import contact information from end-user Facebook or
X (formerly Twitter) accounts. Instead, use the Zendesk REST API. See <a class="xref" href="https://developer.zendesk.com/rest_api/docs/core/users" target="_blank">Importing
users with the Zendesk API</a>.</li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_ltw_lbt_ffc">
<h2 class="title topictitle2" id="ariaid-title3">Creating the CSV organization data file</h2>
<div class="body">
<p class="p">To bulk import organizations, use a CSV organization data file. This section explains how
to set up your CSV data file. </p>
<div class="p">Here are some important things to keep in mind when creating your file:<ul class="ul" id="topic_ltw_lbt_ffc__ul_udk_sct_ffc">
<li class="li">The file must be a properly formatted CSV and saved using UTF-8 character
encoding.</li>
<li class="li">The first row of the CSV file is the header row. </li>
<li class="li">The header row must contain any required fields in the table below, plus any other
fields listed in the table below that you want to include. </li>
<li class="li">In your header row, use either <em class="ph i">domain_names</em> or <em class="ph i">default</em>, depending on
your import method. They can't be used together.</li>
<li class="li">If you are not importing data for a field, do not list it in the header row. </li>
<li class="li">Empty columns of data in the file will overwrite any existing data for that
organization.</li>
<li class="li">Add line breaks to notes or multiline custom fields by pressing ALT+ENTER on Windows
or CTRL+OPTION+RETURN on macOS.</li>
</ul>
</div>
<div class="p">The following table lists the fields that you can include in the file.
<div class="tablenoborder">
<table border="1" cellpadding="4" cellspacing="0" class="table" frame="border" id="topic_ltw_lbt_ffc__table_vdk_sct_ffc" rules="all" summary="">
<caption><span class="tablecap"><span class="table--title-label">Table 1. </span>Organization import data</span></caption>
<colgroup>
<col style="width:23.980815347721823%">
<col style="width:76.01918465227818%">
</colgroup>
<thead class="thead" style="text-align:left;">
<tr class="row">
<th class="entry nocellnorowborder" id="d89e180" style="vertical-align:top;">Field</th>
<th class="entry cell-norowborder" id="d89e183" style="vertical-align:top;">Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr class="row">
<td class="entry nocellnorowborder" headers="d89e180" style="vertical-align:top;">name</td>
<td class="entry cell-norowborder" headers="d89e183" style="vertical-align:top;">
<strong class="ph b">Required</strong>. The organization name.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d89e180" style="vertical-align:top;">external_id</td>
<td class="entry cell-norowborder" headers="d89e183" style="vertical-align:top;">Optional, but recommended; required if you intend to use the data importer to
update these records in the future. A uniquely identifying value, such as an
employee or customer identifying number in an external system.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d89e180" style="vertical-align:top;">notes</td>
<td class="entry cell-norowborder" headers="d89e183" style="vertical-align:top;">Notes about the organization. Notes are visible to agents only, not to end
users. </td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d89e180" style="vertical-align:top;">details</td>
<td class="entry cell-norowborder" headers="d89e183" style="vertical-align:top;">Detailed information about the organization, such as the address. This
information is visible to agents only, not to end users. Use this field instead of
the <em class="ph i">default</em> header when using the data importer.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d89e180" style="vertical-align:top;">domain_names</td>
<td class="entry cell-norowborder" headers="d89e183" style="vertical-align:top;">The organization’s domain names for user mapping. If you're including more
than one domain name for an organization, separate them with a pipe character
(|).</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d89e180" style="vertical-align:top;">group_id</td>
<td class="entry cell-norowborder" headers="d89e183" style="vertical-align:top;">Enter a default group for the organization. See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408882246298#topic_cfj_gfn_bc" target="_blank">Mapping a group to an organization</a>. </td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d89e180" style="vertical-align:top;">tags</td>
<td class="entry cell-norowborder" headers="d89e183" style="vertical-align:top;">When <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408881573658" target="_blank">user and organization tagging</a> has been enabled for
Zendesk Support, you can set tags for the organization. Separate each tag with a
pipe character ( | ). <p class="p">When you bulk import organizations, the tags in your CSV
file replace the existing org tags. To avoid this from happening, consider using
the <a class="xref" href="https://developer.zendesk.com/api-reference/sales-crm/resources/tags/" target="_blank">Tags API</a> to update tags
instead.</p>
</td>
</tr>
<tr class="row">
<td class="entry row-nocellborder" headers="d89e180" style="vertical-align:top;">organization_fields.<em class="ph i">&lt;field
key&gt;</em>
</td>
<td class="entry cellrowborder" headers="d89e183" style="vertical-align:top;">When you perform a bulk organization import, you can import a custom
organization field by specifying the <strong class="ph b">organization_fields.</strong> prefix and the
field key. <p class="p">For example, for the field key <strong class="ph b">subscription_date</strong>, use the
following to set the imported values for this field.</p>
<div class="p">
<pre class="pre" id="topic_ltw_lbt_ffc__pre_nn4_22r_2jc">organization_fields.subscription_date</pre>
</div>
<p class="p">To locate the field key for an org field, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/9199731160474" target="_blank">Finding the field key or field ID for a custom
field</a>.</p>
<p class="p">If a field value is not formatted correctly, the import
will fail, and you will see details about the error in the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5789034291738" target="_blank">import history log</a>. For custom date
fields, use either the YY/MM/DD or YYYY-MM-DD format. For checkbox fields, use
either <em class="ph i">True</em> or
<em class="ph i">False</em>. To set the
value of drop-down field, use the tag you added when you created the drop-down
list.</p>
<div class="note" id="topic_ltw_lbt_ffc__note_on4_22r_2jc">
<span class="notetitle">Note:</span> Lookup relationship fields aren't
supported when importing organizations on the data importer
page.</div>
<p class="p">See <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408842677786" target="_blank">Adding custom fields to organizations</a>.</p>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_hvl_mbt_ffc">
<h2 class="title topictitle2" id="ariaid-title4">Importing organizations with the data importer</h2>
<div class="body">
<p class="p">You can use the data importer to import a CSV file that creates new organizations or
updates existing organizations, and captures logs of all attempted imports through the Data
importer page.</p>
<p class="p">Your import is added to the queue, and the organizations are added to Zendesk Support when
the import process is complete. This should take around an hour per file to complete, but it
does depend on file size and queue size. </p>
<div class="p">
<strong class="ph b">To create or update organizations with the data importer</strong><ol class="ol" id="topic_hvl_mbt_ffc__ol_rn3_515_sxb">
<li class="li"><span class="ph">In <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4581766374554#topic_hfg_dyz_1hb" target="_blank">Admin Center</a>, click <img class="image" id="topic_hvl_mbt_ffc__d9e2086" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_objects_rules_icon.png">
<strong class="ph b">Objects and rules</strong> in the sidebar, then select <strong class="ph b">Tools &gt; Data importer</strong>.</span></li>
<li class="li">Click <strong class="ph b">Import</strong>.</li>
<li class="li">Under <strong class="ph b">Target destination</strong>, select <strong class="ph b">Organization</strong>.</li>
<li class="li">Under <strong class="ph b">Import options</strong>, select one of the following:<ul class="ul" id="topic_hvl_mbt_ffc__ul_jr5_s5t_g1c">
<li class="li">
<strong class="ph b">Create records only</strong>: Only new organizations are created. Any data in the
CSV file pertaining to existing organizations is ignored.</li>
<li class="li">
<strong class="ph b">Update records only</strong>: Replace data for the existing organizations listed in
your CSV file. The <em class="ph i">external_id</em> is required to update organizations. Any data
pertaining to new organizations is ignored.</li>
<li class="li">
<strong class="ph b">Create and update records</strong>: Create new organizations and update data for the
existing organizations listed in your CSV file.</li>
</ul>
</li>
<li class="li">Under <strong class="ph b">File upload</strong>, drag and drop your file or <strong class="ph b">click to upload</strong> and select
your CSV file from the file browser.<p class="p">If you need to change the file you've selected,
click the delete icon (<img class="image" id="topic_hvl_mbt_ffc__image_cfm_mj5_sxb" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/sell_icon_trashcan.png" width="16">) next to the file name.</p>
</li>
<li class="li">Click <strong class="ph b">Next</strong>.</li>
<li class="li">Review the <strong class="ph b">Field mapping</strong> list.<ul class="ul" id="topic_hvl_mbt_ffc__ul_sv3_5j5_sxb">
<li class="li">If the field mapping is correct, click <strong class="ph b">Next</strong>.</li>
<li class="li">If the field mapping isn't correct, click <strong class="ph b">Back</strong>. Edit your CSV file to
adhere to the <a class="xref" href="#topic_ltw_lbt_ffc">format
requirements</a> and then reupload the file.</li>
</ul>
</li>
<li class="li">Review the summary of import details in the confirmation dialog and then click
<strong class="ph b">Start import</strong>.<p class="p">After the import starts, the imported changes can't be
reverted. To check the status of an import, check your <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5789034291738" target="_blank">import history</a>.</p>
</li>
</ol>
</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/4408885980186-Bulk-importing-organization-data-with-the-data-importer",
"url": "https://support.zendesk.com/hc/en-us/articles/4408885980186-Bulk-importing-organization-data-with-the-data-importer",
"headline": "Bulk importing organization data with the data importer",
"description": "You can bulk import or update organization data using a CSV file through the data importer, with specific format requirements and limitations, to manage multiple organizations efficiently.",
"articleSection": "End users and organizations",
"datePublished": "2021-10-16T16:04:21+00:00",
"dateModified": "2026-06-04T22:28:13.459763+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408885980186-Bulk-importing-organization-data-with-the-data-importer"
},
"author": {
"@type": "Organization",
"name": "Zendesk",
"url": "https://www.zendesk.com"
},
"publisher": {
"@type": "Organization",
"name": "Zendesk"
},
"isPartOf": {
"@type": "WebSite",
"name": "Zendesk Help",
"url": "https://support.zendesk.com/hc/en-us"
},
"about": {
"@type": "SoftwareApplication",
"name": "Zendesk"
}
}</script><script id="ai-summary-script">
//<![CDATA[
const ai_summary_style = document.createElement('style');
ai_summary_style.innerHTML = `#styled-article-body{padding:0 0 0}#article-body #docs-ai-summary{background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 6px;margin-bottom:16px}#article-body #docs-ai-summary #docs-ai-summary-toggle{font-size:.9em;font-weight:700;margin-bottom:4px;cursor:pointer;display:flex;justify-content:space-between;align-items:center}#article-body #docs-ai-summary #docs-ai-summary-toggle #up-triangle{margin-left:auto;padding-right:10px;display:none}#article-body #docs-ai-summary #docs-ai-summary-toggle #down-triangle{margin-left:auto;padding-right:10px}#article-body #docs-ai-summary #docs-ai-summary-content{font-size:.9em;padding-left:25px;padding-right:25px;margin-bottom:12px}`;
document.head.appendChild(ai_summary_style);

const toggleAISummary = () => {
const summary = document.getElementById("docs-ai-summary-content");
const upTriangle = document.getElementById("up-triangle");
const downTriangle = document.getElementById("down-triangle");
if (summary.style.display === "none") {
summary.style.display = "block";
upTriangle.style.display = "none";
downTriangle.style.display = "inline";
} else {
summary.style.display = "none";
upTriangle.style.display = "inline";
downTriangle.style.display = "none";
}
};

document.getElementById("docs-ai-summary-toggle").addEventListener("click", toggleAISummary);
//]]>
</script>
</body>