Bulk importing user data with the data importer

<body>
<p id="docs-hc-snippet" style="display: none;">Admins can add many users in a bulk import rather than adding users manually one at a time. To do this, you create a comma-separated values (CSV) file that contains the user's data. In addition to essential user data, such as email address and phone number, you can also set user roles, define an agent's privileges, and add users to an organization. You can use bulk import to either add new users or update existing ones. Bulk import through a CSV file only works for Support users and roles.</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 use a CSV file to bulk import or update users, set roles, ticket restrictions, groups, organizations, phones, tags, and custom fields, and create or update multiple records at once. The importer works only for Support users, has file size and format limits, and may send welcome emails unless you turn that off. It also keeps import history and error reports for failed rows.</p>
</div>

<div class="body">

<div class="note fastpath">
<span class="fastpathtitle">Location: </span> <span class="ph">Admin Center &gt; Objects and rules &gt; Tools &gt; Data importer</span>
</div>
<p class="p">Admins can add many users in a bulk import rather than adding users manually one at a
time. To do this, you create a comma-separated values (CSV) file that contains the
user's data. In addition to essential user data, such as email address and phone number,
you can also set user roles, define an agent's privileges, and add users to an
organization. You can use bulk import to either add new users or update existing ones.
Bulk import through a CSV file only works for Support users and roles.</p>
<p class="p">You must be an administrator to bulk import users and organizations.</p>
<p class="p">If you're using the legacy method to import user data through the Bulk actions pages, see
<a class="xref" href="https://support.zendesk.com/hc/en-us/articles/10077720640026" target="_blank">Bulk importing user data (legacy)</a>.</p>
<div class="p">
<div class="note important">
<span class="importanttitle">Important:</span>
<ul class="ul" id="topic_fdc_jkx_2fc__ul_enz_vv1_5cc">
<li class="li">To protect the data in your Zendesk account, data imports are not enabled by
default. The account owner or an admin must contact <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408843597850" target="_blank">Zendesk Customer Support</a> to enable
data imports and access to the imports
page.</li>
<li class="li">If you want to bulk import both users and organizations, you must <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408885980186" target="_blank">import organizations</a> first.</li>
</ul>
</div>
</div>
<div class="p">This article contains the following topics:<ul class="ul" id="topic_fdc_jkx_2fc__ul_cp1_mkx_2fc">
<li class="li"><a class="xref" href="#topic_vpj_tl1_5cc">Considerations for bulk importing users</a></li>
<li class="li"><a class="xref" href="#topic_svw_jdl_dc">Creating the CSV user data file</a></li>
<li class="li"><a class="xref" href="#topic_syb_lm1_5cc">Using the data importer to import user data</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title2" class="topic nested1" id="topic_vpj_tl1_5cc">
<h2 class="title topictitle2" id="ariaid-title2">Considerations for bulk importing users</h2>
<div class="body">
<div class="p">There are a variety of limitations and considerations you should review prior to bulk
importing users:<ul class="ul" id="topic_vpj_tl1_5cc__ul_ocq_dm1_5cc">
<li class="li"><a class="xref" href="#id_j2z_vlx_2fc">Limitations for bulk importing
with the data importer</a></li>
<li class="li"><a class="xref" href="#topic_bck_td1_zg">Updating existing user profile data</a></li>
<li class="li"><a class="xref" href="#topic_cvj_4rx_jh">Deciding whether to send an email to users imported in bulk</a></li>
</ul>
</div>
</div>
<div aria-labelledby="ariaid-title3" class="topic nested2" id="id_j2z_vlx_2fc">
<h3 class="title topictitle3" id="ariaid-title3">Limitations for bulk importing with the data importer</h3>
<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_j2z_vlx_2fc__d9e28">
<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-title4" class="topic nested2" id="topic_bck_td1_zg">
<h3 class="title topictitle3" id="ariaid-title4">Updating existing user profile data</h3>
<div class="body">
<div class="p">When performing a bulk import, you can update existing users. Be aware that some
data is replaced, and some is just appended to the existing data. <div class="note" id="topic_bck_td1_zg__note_l1y_2rl_4hc">
<span class="notetitle">Note:</span> To update an existing user, the CSV file must include
the user's name, email address, or external id so that Zendesk can identify
them.</div>
</div>
</div>
<div aria-labelledby="ariaid-title5" class="topic nested3" id="topic_y5x_dxg_g2c">
<h4 class="title topictitle4" id="ariaid-title5">How data is updated by the data importer</h4>
<div class="body">
<div class="p">When using the data importer, only the following user data is appended (added
to the existing data):<ul class="ul" id="topic_y5x_dxg_g2c__ul_kdk_cxg_g2c">
<li class="li">phones (added as a secondary phone numbers)</li>
<li class="li">emails (added as a secondary email addresses)</li>
</ul>
</div>
<p class="p">All other data is replaced by the data importer.</p>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title6" class="topic nested2" id="topic_cvj_4rx_jh">
<h3 class="title topictitle3" id="ariaid-title6">Deciding whether to send an email to users imported in bulk</h3>
<div class="body">
<p class="p">Before you perform a bulk import of users, it's important to <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408824350746" target="_blank">check your welcome email settings</a>.
When you add new users via a bulk import while Guide is enabled, each user
receives the welcome email message. The welcome email contains a link to verify
their email address, which prompts them to select a password and then sign in.
You can prevent the welcome email from being sent to these users.</p>
<p class="p"><strong class="ph b">To prevent the welcome email message being sent to users</strong></p>
<div class="p">
<ol class="ol" id="topic_cvj_4rx_jh__ol_bsp_qsx_jh">
<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_cvj_4rx_jh__d10e826" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_people_icon.png">
<strong class="ph b">People</strong> in the sidebar, then select <strong class="ph b">Configuration &gt; End users</strong>.</span></li>
<li class="li">In the <strong class="ph b">User welcome email</strong> section, deselect <strong class="ph b">Also send a
verification email when a new user is created by an agent or
administrator</strong>.<p class="p"><img class="image img-screenshot" id="topic_cvj_4rx_jh__image_tn1_hqc_bq" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/bulk_import_disable_welcome_email.png"></p>
</li>
<li class="li">Click <strong class="ph b">Save</strong>.</li>
</ol>
</div>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title7" class="topic nested1" id="topic_svw_jdl_dc">
<h2 class="title topictitle2" id="ariaid-title7">Creating the CSV user data file</h2>
<div class="body">
<p class="p">When you create a list of users to import, you'll probably generate this list from
some other user management system, such as an employee database. Most of these
systems have some facility for creating a CSV export file. If you need to create the
list from scratch, you can use a program like Microsoft Excel or OpenOffice.org
Calc. </p>
<div class="p">Here are some important things to keep in mind when creating your file:<ul class="ul" id="topic_svw_jdl_dc__ul_bkp_yh3_1w">
<li class="li">You can download a CSV template in Admin Center &gt; Data importer &gt; Import &gt;
<strong class="ph b">Download a CSV template</strong>.</li>
<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, and you must include it in
the file. </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">Included fields must appear in the header row in the order they are listed
below.</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 most existing data for that
user. For exceptions, see <a class="xref" href="#topic_bck_td1_zg">Updating existing user profile data</a>.</li>
<li class="li">Add line breaks to notes or multiline custom fields by pressing ALT+ENTER on
Windows or CTRL+OPTION+RETURN on a Mac.</li>
</ul>
</div>
<div class="p">
<div class="note" id="topic_svw_jdl_dc__note_m1y_2rl_4hc">
<span class="notetitle">Note:</span> Microsoft Excel cannot save your file immediately. To
save your file, upload it to Google Sheets, re-download it, and then upload it
to Zendesk. You can also use Open Office to save the file. </div>
</div>
<p class="p">The following table lists the fields that you can include in the file. The name,
email, and restriction fields are all required when importing new users. When
existing users are updated via bulk import, only one unique identifier is required
(such as an email or external ID).</p>
<div class="p">
<div class="tablenoborder">
<table border="1" cellpadding="4" cellspacing="0" class="table" frame="border" id="topic_svw_jdl_dc__table_rhi_mel_dc" rules="all" summary="">
<caption><span class="tablecap"><span class="table--title-label">Table 1. </span>User import data</span></caption>
<colgroup>
<col style="width:22.98850574712644%">
<col style="width:77.01149425287358%">
</colgroup>
<thead class="thead" style="text-align:left;">
<tr class="row">
<th class="entry nocellnorowborder" id="d90e337" style="vertical-align:top;">Field</th>
<th class="entry cell-norowborder" id="d90e340" style="vertical-align:top;">Description</th>
</tr>
</thead>
<tbody class="tbody">
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">name</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">
<em class="ph i">Required for importing new users.</em> User's full name.
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">emails</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">
<em class="ph i">Required for importing new users.</em> User's full email
address (someuser@mycompany.com). If including more than one
email address for a user, separate them by a pipe (|). For
example:
<code class="ph codeph">first@yourcompany.com|second@yourcompany.com</code>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">alias</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">An alias displayed to end users.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">brand_id</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">If the account has multiple brands, include the ID of the
brand the user should be associated with.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">custom_role</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">When the role is set to Agent, specify the custom role name,
as listed on the <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4409148517658" target="_blank">Roles page</a> in Admin
Center. <strong class="ph b">Light agent</strong> is also accepted.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">default_group_id</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">
<p class="p">New team members (admins and agents) are automatically added
to the account's <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408828237722" target="_blank">default group</a>.
However, you can use this field to specify alternative
default groups for users during bulk imports. When you
change a user's default group, they will still be a member
of their previous groups (including their previous default
group).</p>
<p class="p">End users can't be added to groups.</p>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">details</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Detailed information concerning this user, such as an
address. This information is visible to team members only, not
to end users.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">external_id</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">If you have an ID other than the user's email address (such
as an employee ID or customer reference number), you can include
it here. External IDs must be unique for each user, or data will
be overwritten.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">locale</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">The user's locale. A BCP-47 compliant tag for the locale
(e.g. en-US). If both locale and locale_id are present,
locale_id is ignored and only locale is used.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">local_id</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">The user's language identifier.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">moderator</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Boolean. Designates whether the user has forum moderation
capabilities.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">notes</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Notes concerning this user. Notes are visible to team members
only, not to end users.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">only_private_comments</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Boolean. When set to <strong class="ph b">true</strong>, the user can only create
private comments.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">organizations</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">The name of the organization that the user will be added to.
The organization must already exist, or the import will fail.
<p class="p">On Professional and Enterprise plans, you can add a user
to multiple organizations by separating the organization
names with a pipe character. For example:
<code class="ph codeph">Organization1|Organization2|Organization3</code>.
A maximum of 50 organizations are allowed.
</p>
<p class="p">A user's default organization
is set to the first organization alphabetically. It isn't
possible to set a different default organization during a
bulk import. However, the default organization for a user
can be adjusted manually or with the <a class="xref" href="https://developer.zendesk.com/api-reference/ticketing/organizations/organization_memberships/#set-membership-as-default" target="_blank">Ticketing API - Set Membership as
Default</a> endpoint.</p>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">phones</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">The user's telephone numbers. Unique phone numbers are added
as direct lines. Phone numbers that already exist are added as
secondary lines. If you're including more than one phone number
for a user, separate the phone numbers with a pipe (|). <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408823756570" target="_blank">To work with Zendesk</a>,
phone numbers should be formatted with the internationally
standardized <a class="xref" href="https://en.wikipedia.org/wiki/E.164" target="_blank">E.164</a> format.
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">remote_photo_url</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">A URL pointing to the user's profile picture.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">role</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Case sensitive: <strong class="ph b">end-user</strong> or <strong class="ph b">agent</strong>. If you don't
set a role, the user is set to <strong class="ph b">end-user</strong>. </td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">shared_phone</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">The user's shared telephone number. <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408823756570" target="_blank">To work with Zendesk</a>,
phone numbers should be formatted with the internationally
standardized <a class="xref" href="https://en.wikipedia.org/wiki/E.164" target="_blank">E.164</a> format.
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">signature</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">The user's signature. Only agents and admins can have
signatures.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">skip_verify_email</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">If you need to create users without sending out a
verification email, set this value to <strong class="ph b">true</strong>.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">suspended</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Boolean. Indicates whether the user is suspended. Tickets
from suspended users are also suspended, and these users cannot
sign in to the end-user portal.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">tags</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">When user and organization tagging has been enabled for
Zendesk Support (see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408881573658" target="_blank">Adding tags and users to
organizations</a>), you can add user tags. Separate each
tag with a comma.</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">ticket_restriction</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Restriction sets the team member's or end user's privileges,
the tickets they have access to, and so on. This is required to import
new users when the user's role is set to Agent. <div class="p">On
non-Enterprise plans, the following restriction values are
supported:<ul class="ul" id="topic_svw_jdl_dc__ul_jfx_dpn_g2c">
<li class="li">
<strong class="ph b">assigned</strong>: The team member can access only
tickets assigned to them.</li>
<li class="li">
<strong class="ph b">groups</strong>: The team member can access only
tickets within their group(s). To add a team member
to a group, see <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408821536794" target="_blank">Viewing and
managing team member group membership</a> or
use the <a class="xref" href="https://developer.zendesk.com/api-reference/introduction/introduction/" target="_blank">Zendesk
API</a>.</li>
<li class="li">
<strong class="ph b">none</strong>: The user has no restrictions and can
access all tickets. </li>
<li class="li">
<strong class="ph b">organization</strong>: The user can access only
tickets requested by them or other users in their
organization.</li>
<li class="li">
<strong class="ph b">requested</strong>: The user can access only their own
tickets. They must be listed as the ticket's
requester.</li>
</ul>
</div>
Restriction values of <strong class="ph b">organization</strong> and
<strong class="ph b">requested</strong> can be assigned when the user's role is set
to End-user. All others apply only to team members.
<div class="note" id="topic_svw_jdl_dc__note_n1y_2rl_4hc">
<span class="notetitle">Note:</span> On Enterprise plans, agent roles
override the standard agent restrictions. This means that
you can't use any of the standard restrictions listed in the
table above to import or update an agent. You must specify
an agent role. If you accidentally use a role name that
doesn't exist in Support, the user's role defaults to Light
Agent.</div>
</td>
</tr>
<tr class="row">
<td class="entry nocellnorowborder" headers="d90e337" style="vertical-align:top;">time_zone</td>
<td class="entry cell-norowborder" headers="d90e340" style="vertical-align:top;">Consists of a string such as "Eastern Time (US &amp;
Canada)". For a list of valid names, view the Time zone list
menu on the Localization page (Account &gt; Appearance &gt;
Localization) in Admin Center. Example: If the menu lists
"(GMT+02:00) Berlin", then use "Berlin" as the time_zone
name.</td>
</tr>
<tr class="row">
<td class="entry row-nocellborder" headers="d90e337" style="vertical-align:top;">custom_fields.<em class="ph i">&lt;field key&gt;</em>
</td>
<td class="entry cellrowborder" headers="d90e340" style="vertical-align:top;">When you perform a bulk user import, you can import a custom
user field by specifying
the <code class="ph codeph">custom_fields.</code> prefix and the field
key. <p class="p">For example, for the field
key <code class="ph codeph">subscription_date</code>, use the
following to set the imported values for this field.</p>
<div class="p">
<pre class="pre" id="topic_svw_jdl_dc__pre_p1y_2rl_4hc">custom_fields.subscription_date</pre>
</div>
<p class="p">Custom field keys are case-sensitive and must be entered
in lowercase letters. </p>
<p class="p">If you are importing
information into a checkbox, enter <strong class="ph b">true</strong> to have it
checked or <strong class="ph b">false</strong> to leave it unchecked. To set the
value of drop-down list options, use the tag you added when
you created the drop-down list. For custom date fields, use
either the YY/MM/DD or YYYY-MM-DD format.</p>
<div class="p">To locate
the key for a custom user field:<ul class="ul" id="topic_svw_jdl_dc__ul_yry_spp_wqb">
<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_svw_jdl_dc__d10e750" src="https://zen-marketing-documentation.s3.amazonaws.com/docs/en/ac_people_icon.png">
<strong class="ph b">People</strong> in the sidebar, then select <strong class="ph b">Configuration &gt; User fields</strong>.</span> Then, click the name of the custom field.
The field key appears in the properties panel on the
right.</li>
</ul>
</div>
<p class="p">If a field value is not formatted correctly, the
import will fail, and you will receive an error report
specifying which records failed to save. </p>
<div class="note" id="topic_svw_jdl_dc__note_q1y_2rl_4hc">
<span class="notetitle">Note:</span> If the custom user field you're
importing is a <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4591924111770" target="_blank">lookup relationship
field</a>, enter the ID of the related object as the
value for this field. For example, for an organization,
enter the organization's ID; for a user, enter the user's
ID; for a custom object record, enter the record's ID. To
find an organization, user, or custom object record ID, you
can <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/4408886165402" target="_blank">export data from your
account</a> or use the <a class="xref" href="https://developer.zendesk.com/api-reference/ticketing/organizations/organizations/#list-organizations" target="_blank">Organizations API</a>,
<a class="xref" href="https://developer.zendesk.com/api-reference/ticketing/users/users/#list-users" target="_blank">Users API</a>, or
<a class="xref" href="https://developer.zendesk.com/api-reference/custom-data/custom-objects/custom_object_records/#list-custom-object-records" target="_blank">Custom Object Records
API</a>.</div>
</td>
</tr>
</tbody>
</table>
</div>
</div>
</div>
</div>
<div aria-labelledby="ariaid-title8" class="topic nested1" id="topic_syb_lm1_5cc">
<h2 class="title topictitle2" id="ariaid-title8">Using the data importer to import user data</h2>
<div class="body">
<p class="p">You can use the data importer to import a CSV file that creates or updates existing
users, and captures logs of all imports attempted through the Data importer
page.</p>
<div class="p">
<strong class="ph b">To add or update users with the data importer</strong><ol class="ol" id="topic_syb_lm1_5cc__ol_k2x_zm1_5cc">
<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_syb_lm1_5cc__d10e2132" 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">Users</strong>.</li>
<li class="li">Under <strong class="ph b">Import type</strong>, choose one of the following:<ul class="ul" id="topic_syb_lm1_5cc__ul_ext_dn1_5cc">
<li class="li">
<strong class="ph b">Create only</strong>: Only new users are added. Any data in the CSV
file pertaining to existing users is ignored.</li>
<li class="li">
<strong class="ph b">Update only</strong>: Update data for the existing users listed in
your CSV file. </li>
<li class="li">
<strong class="ph b">Create and update</strong>: Add new users and update data for the
existing users listed in your CSV file.</li>
</ul>
<div class="note" id="topic_syb_lm1_5cc__note_r1y_2rl_4hc">
<span class="notetitle">Note:</span> If any external ID, email address, or phone
number matches more than one existing user, that row is rejected from
the bulk import. Check your <a class="xref" href="https://support.zendesk.com/hc/en-us/articles/5789034291738" target="_blank">import history</a>. </div>
</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_syb_lm1_5cc__image_qnq_nn1_5cc" 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_syb_lm1_5cc__ul_grv_4n1_5cc">
<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_svw_jdl_dc">format requirements</a>, 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/4408893496218",
"url": "https://support.zendesk.com/hc/en-us/articles/4408893496218",
"headline": "Bulk importing user data with the data importer",
"description": "You create a CSV file to import or update users in bulk, including roles and organization data, then use the data importer to upload, map fields, and start the import.",
"articleSection": "Team members and groups",
"datePublished": "2021-10-16T17:09:17+00:00",
"dateModified": "2026-08-31T22:24:05.767368+00:00",
"inLanguage": "en",
"mainEntityOfPage": {
"@type": "WebPage",
"@id": "https://support.zendesk.com/hc/en-us/articles/4408893496218"
},
"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": "People and access",
"@id": "https://support.zendesk.com/hc/en-us/sections/5283086413338"
}
}
}</script><script id="fast-path-script">
//<![CDATA[
const fast_path_style = document.createElement('style');
fast_path_style.innerHTML = `#article-body .fastpath{font-size:.9em;background-color:#f3f3f3;border:1px solid #d3d3d3;padding:10px 10px 8px;margin-bottom:16px}#article-body .fastpath::before{content:none!important}`;
document.head.appendChild(fast_path_style);
//]]>
</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>