Bulk importing custom object records

<body>
<p id="docs-hc-snippet" style="display: none;">Rather than adding custom object records one at a time, you can bulk-add and update many records at once by importing a CSV (comma-separated values) file. You must be an administrator to bulk import custom object records.</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_e">
<table>
<tbody>
<tr>
<td>
<strong>Support</strong>
</td>
<td>Enterprise</td>
</tr>
</tbody>
</table>
</div>

</div>

<div class="body">

<p class="p">Rather than adding custom object records one at a time, you can bulk-add and update many
records at once by importing a CSV (comma-separated values) file. You must be an
administrator to bulk import custom object records.</p>
<div class="p">This article contains the following topics:<ul class="ul" id="topic_e3v_3qh_qyb__ul_jst_cl3_qyb">
<li class="li"><a class="xref" href="#topic_r1d_dl3_qyb">Requirements and limitations</a></li>
<li class="li"><a class="xref" href="#topic_pyb_pm3_qyb">Creating custom object records CSV file</a></li>
<li class="li"><a class="xref" href="#topic_mtp_rm3_qyb">Importing the custom object records CSV file</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_r1d_dl3_qyb">
<h2 class="title topictitle2" id="ariaid-title2">Requirements and limitations</h2>
<div class="body">
<div class="p">The following limitations of bulk importing apply:<ul class="ul" id="topic_r1d_dl3_qyb__ul_vtk_lll_dc">
<li class="li">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 32 KB in size.</li>
<li class="li">The import CSV file can contain a maximum of 102 columns.</li>
<li class="li">Don't include the same record 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.</li>
<li class="li">Bulk importing custom object records can't be undone. Before importing the
CSV file that contains the information of all your current records, test
that same CSV file with a single record to make sure the upload works as
intended.</li>
</ul>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested1" id="topic_pyb_pm3_qyb">
<h2 class="title topictitle2" id="ariaid-title3">Creating custom object records CSV file</h2>
<div class="body">
<div class="p">To bulk import custom object records, you will use a CSV file. Here are some
important things to keep in mind when creating your file:<ul class="ul" id="topic_pyb_pm3_qyb__ul_sjx_ph3_1w">
<li class="li">The file must be 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 a <strong class="ph b">name</strong> field. Optionally, if you wish to
bulk update the records in the future, you must also include an
<strong class="ph b">external_id</strong> field. All other field names in the header row should
be exact matches to the field keys in your custom object.</li>
<li class="li">To import values for dropdown fields, use the custom dropdown field's
<strong class="ph b">field_key</strong> as the column heading and specify the options
<strong class="ph b">tag</strong>, not the user-friendly value. </li>
<li class="li">To import multiple values for a multi-select field, provide a
space-separated list of the values'
tags.</li>
<li class="li">To import values for lookup relationship fields, use the custom lookup
relationship field's <strong class="ph b">field_key</strong> as the column heading and provide
either the record's <strong class="ph b">id</strong> or <strong class="ph b">external id</strong>. If you use the record's
<strong class="ph b">ID</strong>, provide the value. If you use the <strong class="ph b">External ID</strong>, use the
format <strong class="ph b">external_id:<em class="ph i">value</em></strong>, where <em class="ph i">value</em> is replaced with
the related record's external ID value.</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">Add line breaks to notes or multiline custom fields by pressing ALT+ENTER on
Windows or CTRL+OPTION+RETURN on macOS.</li>
</ul>
</div>
<p class="p">If you are performing a bulk upload of records to seed your existing data for a new
custom object, we recommend that you walk through <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/6070642803610" target="_blank">Planning your custom objects workflow</a>. During the
process, we recommend creating spreadsheets with this data for each of your custom
objects. If structured carefully to align with the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5392409465370" target="_blank">custom object you created in Zendesk</a> and the guidelines
above, you can export the spreadsheet as a CSV file and use it for this bulk upload.
In this case, make sure to add a column for the <strong class="ph b">external_id</strong> and add an ID for
each record if you want the option of bulk updating them in the future.</p>
</div>
</div>
<div aria-labelledby="ariaid-title4" class="topic nested1" id="topic_mtp_rm3_qyb">
<h2 class="title topictitle2" id="ariaid-title4">Importing the custom object records CSV file</h2>
<div class="body">
<p class="p">You can use the data importer to import a CSV file that creates new custom object
records or updates existing records and capture logs of all attempted imports
through the Data importer page.</p>
<div class="p">
<strong class="ph b">To create or update custom object records with the data importer</strong><ol class="ol" id="topic_mtp_rm3_qyb__ol_rn3_515_sxb">
<li class="li">Before you can bulk upload records for a custom object, you must <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5392409465370" target="_blank">create the custom object in
Zendesk</a>.</li>
<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_mtp_rm3_qyb__d8e2056" 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">Import type</strong>, choose one of the following:<ul class="ul" id="topic_mtp_rm3_qyb__ul_jr5_s5t_g1c">
<li class="li">
<strong class="ph b">Create only</strong>: Only new custom object records are created. Any
data in the CSV file pertaining to existing records is ignored.</li>
<li class="li">
<strong class="ph b">Update only</strong>: Replace data for the existing custom object
records listed in your CSV file. Any data pertaining to new records
is ignored.</li>
<li class="li">
<strong class="ph b">Create and update</strong>: Create new custom object records and
update data for the existing custom object records listed in your
CSV file.</li>
</ul>
</li>
<li class="li">Under <strong class="ph b">Target destination</strong>, select the custom object's name.</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_mtp_rm3_qyb__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_mtp_rm3_qyb__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_pyb_pm3_qyb">format requirements</a>, and then re-upload 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/6100391508250-Bulk-importing-custom-object-records",
"url": "https://support.zendesk.com/hc/en-us/articles/6100391508250-Bulk-importing-custom-object-records",
"headline": "Bulk importing custom object records",
"description": "You can bulk import and update custom object records by uploading a properly formatted CSV file with specific size and formatting requirements through the data importer tool, ensuring accurate field mapping and adherence to limitations.",
"articleSection": "Custom data",
"datePublished": "2023-09-01T12:06:29+00:00",
"dateModified": "2026-05-21T15:50:20.259279+00:00",
"inLanguage": "en-US",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/6100391508250-Bulk-importing-custom-object-records"
},
"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>
</body>