Rather than add users manually one at a time, admins can add many users in a bulk import. To do this, you create a CSV (comma separated values) file that contains the user's data. Aside from the essential user data, such as email address and phone number, you can 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 via a CSV file only works for Support users and roles.
You must be an administrator to bulk import users and organizations.
Limitations of bulk importing users and organizations
You can import a core set of data about users and organizations. For example, using bulk import, you can import the data described in the table below; however, you cannot import timezones, photos, language preferences, etc. To import data not listed in the table below, you need to use the Zendesk REST API instead. See Importing users with the Zendesk API or Importing organizations with the Zendesk API.
- The maximum number of rows depends on the import method.
- For user data and updating existing organization data, the import CSV data file can contain a maximum of 2,000 rows . That is, one header row and up to 1,999 rows of data.
- For new organization data using the Data importer (beta), 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.
- When using the Data importer, the following limitations also apply:
- The import CSV file can contain a maximum of 200 columns.
- The import CSV file can't guarantee import order for rows.
- 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.
- You cannot use bulk importing to import contact information from end-user Facebook or Twitter accounts. Instead, use the Zendesk REST API. See Importing users with the Zendesk API.
Creating the CSV user data file
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.
- The file must be properly formatted CSV and saved using UTF-8 character encoding.
- The first row of the CSV file is the header row, and you must include it in the file.
- 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.
- Included fields must appear in the header row in the order they are listed below.
- If you are not importing data for a field, do not list it in the header row.
- Empty columns of data in the file will overwrite most existing data for that user. For exceptions, see Updating existing user profile data.
- Add line breaks to notes or multiline custom fields by pressing ALT+ENTER on Windows or CTRL+OPTION+RETURN on a Mac.
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).
Field | Description |
---|---|
name | Required for importing new users. User's full name. |
Required for importing new users. User's full email address (someuser@mycompany.com). You can give users more than one email address. See Assigning multiple email addresses to a user. | |
external_id | 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. If you don’t enable Include external ID in CSV output file, external IDs are excluded from the CSV import results file (see Importing the CSV user data file). Note: If you import users with
the external_id field as their only identifier (meaning you're not also
including email address), you still need to include the email field in the CSV
file, with no data. For example:
|
details | Detailed information concerning this user, e.g. an address. This information is visible to team members only, not to end-users. |
notes | Notes concerning this user. Notes are visible to team members only, not to end users. |
phone | The user's telephone numbers. Unique phone numbers are added as direct lines. Phone numbers that already exist are added as secondary lines. To work with Talk, phone numbers should be formatted with the internationally standardized E.164 format. |
shared_phone_number | If this is a shared phone number, set to "true". A shared phone number cannot be used as a user identity. |
role | Case sensitive: "End-user", "Agent", or "Admin". If you don't set a role, the user is set to End user. |
restriction | Required for importing new users when the user's role is set to
"Agent". Restriction values of "organization" and "requested" can be
assigned when the user's role is set to "End-user".
Restriction sets the team member's or end user's privileges,
the tickets they have access to, etc. You can enter one of the following
values:
In the Enterprise version of Zendesk Support, you can also use the restriction field to assign your agent users predefined or custom roles. See Assigning an agent to an Enterprise agent role below. |
organization | The name of the organization that the user will be added to. The organization
must already exist or the import will fail. On Professional and Enterprise, you can add a user to multiple organizations by separating the organization names with a pipe character (see Importing users into multiple organizations). |
tags | When user and organization tagging has been enabled for Zendesk Support (see see Adding tags and users to organizations), you can add user tags. Separate each tag with the comma. |
brand | If the account has multiple brands, you can specify a brand subdomain. The
brand subdomain you specify determines the brand of the welcome email sent to the
user, as long as that brand is active and has an enabled help center. If the brand
subdomain you specify is not active, doesn't have an enabled help center, or
doesn't exist, the column is ignored and the welcome email is sent using default
brand. Specify only the name of the brand subdomain. For example, use mydomain and not mydomain.zendesk.com. |
custom_fields.<field key> | When you perform a bulk user import, you can import a custom user field by
specifying the custom_fields. prefix and the field key. For example, for the field key subscription_date, use the following to set the imported values for this field. custom_fields.subscription_date Note that custom field keys are case-sensitive and must be entered in lowercase letters. If you are importing information into a checkbox, enter 'true' to have it checked or 'false' 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. To locate the key for a custom user field:
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. Note: If the custom user field you're importing is a lookup relationship field, 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. To
find an organization or user ID, you can export data from your account or use the
Organizations API or Users
API.
|
A note about welcome email sent to users in a bulk import
When you add new users via a bulk import, each user receives the welcome email message, if you have Guide enabled. 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 all these users by updating the welcome email setting.
To prevent the welcome email message being sent to users
- In Admin Center, click
People in the sidebar, then select Configuration > End users.
- In the User welcome email section, deselect Also send a verification email
when a new user is created by an agent or administrator.Note: This option is not available until you enable Guide.
- Click Save tab.
Importing users into multiple organizations
If you're on Professional or Enterprise, you can add users to multiple organizations during your bulk import.
Organization1|Organization2|Organization3
Here's a CSV example for adding a user to three different organizations.
"name","email","external_id","details","notes","phone","role","restriction","organization","tags"
Enrico Venticello,"venticello@somecompany.com",,,,,,,Organization1|Organization2|Organization3,,
If you list an organization that does not exist, the import will fail.
A user's default organization will be set to the first organization alphabetically. It is not possible to set a different default org using the .csv import. The default organization for a user can be adjusted manually or by using theSupport API - Set Membership as Default endpoint.
Assigning an agent to an Enterprise custom role
On Enterprise, you can assign agents custom roles. Custom roles are often used to give agents extra permissions or increased restrictions.
If you created your own custom agent roles, you can assign one of these roles to users during a bulk import by including the name of the custom role in the restriction field. In the following CSV example, a user is assigned a custom role:
"name","email","external_id","details","notes","phone","role",
"restriction","organization","tags"
Enrico Venticello,"venticello@somecompany.com",,,,,"agent","Help Desk Mastermind",,
In the example above, the user (Enrico Venticello) is given a general role ("agent"), with the additional permissions associated with the custom agent role ("Help Desk Mastermind").
Note that you must have already created the custom role in Zendesk Support before you can use it in your CSV. If you accidentally use a role name that doesn't exist in Support, the user's role defaults to Light Agent. You can then manually change the agent's role in their user profile.
Also, the import is case insensitive, which means that both of following custom role names set the agent to the same role: "Help Desk Mastermind" and "help Desk mastermind".
Assigning multiple email addresses and phone numbers to a user
In the upload file, give the same external ID (and all the user fields to be imported, for example, role) to more than one email address or phone number, as shown in the image above. All emails or calls associated with the same external ID will be routed to the user associated with that ID.
Note that when the email address matches an existing user and there are no mismatches on the external ID or phone number, that user is updated with the secondary email or new phone number. However, if any external ID, email address, or phone number matches more than one existing user, that row is rejected.
Importing the CSV user data file
You can import new users or update information for existing users.
- In Admin Center, click
People in the sidebar, then select Bulk actions > Import users.
- Select import options:
-
Create new users: This is selected by default and cannot be disabled. This is because users that exist in the import data, but not in Zendesk, will always be created.
-
Update existing users: You can additionally select this import option to replace existing data for the users listed in your CSV file.
Users' external_id or email address must be included in the CSV so that they can be identified. Other than a user identifier field, you only need to include the fields that you want to update in the file. If a user's row has a blank field, it will overwrite the existing data for that user. See Updating existing user profile data.
Note: The Send email notification to users if their password is changed option is not currently available.
-
- (Optional) Select Include external ID in CSV output file.
When the import process is complete, you will receive an email notification that includes a link to a separate CSV import results file. You can use this link to download the file and view the results of your import.
The file shows the status of the user data that you attempted to import (Created, Updated, Skipped). It includes the email address or an external ID for each user that is created or updated, depending on the contents of the file you imported and whether Include external ID in CSV output file was enabled.
If you don’t enable Include external ID in CSV output file, external IDs are excluded from the CSV import results file. External IDs are additional identifiers such as an employee number, customer reference number, or a user ID from another system. A user can only have one unique external ID. It is an optional attribute for users.
- Either click Choose File or the Let me paste in data instead link.
- Click Import.
Your import is added to the queue and the users are added to Zendesk Support when the import process is complete. See Limitations of bulk importing users and organizations. You'll receive an email when the import is complete.
Updating existing user profile data
The following user data is replaced:
- name
- external_idNote: External IDs must be unique for each user.
- role
- restriction
- organization
- Custom fields
The following user data is appended (added to the existing data):
- details
- notes
- tags
- phone (added as a secondary phone number)
- email (added as a secondary email address)
60 Comments
Hello @... and @...! I am trying to delete the phone numbers for all 23k end_users that we have. I wrote a script to be able to iterate through users, pull their user identity id if it is a phone number, and then delete it via API. However, I'm noticing despite a status code 204, in many cases, I still see the phone number from the UI, despite it no longer being available when I've queried it via API. On other occasions, deleting the user identity does remove the phone number from the UI. This leaves me to believe that sometimes phone numbers (not yet clear when) are stored on both the phone field of the user AND as a user identity, and that deleting user identity does not actually remove it from the user. It is really hard to get clarity on how you all are actually storing the phone number. Could someone from the Zendesk team please elucidate for me how to permanently delete phone numbers and/or hide it from our agents?
Hi @...,
A phone number can be stored as a direct line or a shared line. We go into some more detail here: Understanding how phone numbers are linked to end-user profiles
However I don't think that solves the issue you are facing, and it may be worth taking this into a ticket to figure out the answer.
I'll reach out to you from the ticket I create about your issue. Once we find the solution we can post it back here.
Hello,
We used to replace all our user's tag just with the csv, is there a simple way to have the overwriting behavior using the csv?
Hi Beatriz,
Unfortunately, updating users via CSV can only append new user tags, it cannot overwrite existing user tags. See Updating existing user profile data
In order to bulk-update the user tags of a number of users at once, you'd need to use the API: Create Or Update Many Users
If you haven't used the API before, this introduction could be helpful: Introduction
What about groups? They are not mentioned.

Zendesk Support tells me it's actually "impossible" to update groups using this method. If it's not impossible (which I suspect it's not), can you please update this article with some clearer instructions on how to import restrictions like groups?
Hey CJ,
You are correct and you cannot set an agent's group via CSV bulk import. There are only two options available for updating a users group:
Since this article is specifically addressing bulk importing users, I'm thinking we will want to create a separate article that discusses how someone can update group assignments in bulk outside of a CSV file.
Appreciate you bringing this to our attention!
Hi CJ Johnson,
I thought I'd mention one of my favorite ways to update Agents' groups is to go to Admin -> Manage -> People and select Groups. Or go here: https://YOURDOMAIN.zendesk.com/agent/admin/people and select Groups
Select the Group you want to update - and click edit all the way to the right of the screen. There, you can simply check the Agents you want to add to a group.
@...


Maybe it would be good then, to remove all the references in this article that say you can do this? Based on the article comments this certainly used to be possible, so it's extremely confusing to have left it in. This deprecation/removal does not appear to be mentioned in any release notes either.
@...
Unfortunately, that's a non-starter. I'm not going to click 100-200 names by hand every time I need to make mass updates, one because that's really tedious, and two, because it's prone to human error. Getting a CSV import file with errors on the ones that failed for this task is highly, highly preferable, although given that it was apparently removed, and would overwrite, not append groups, previously, I'm not sure that really met my needs either. I'll likely end up spending some time writing out some API scripts to accomplish this task, though it won't be quite as nice or accessible to less technical folks.
This article is *still* outdated and claims you can update groups using the import.
Hi CJ –
Thanks for your feedback here, we've adjusted the text about on groups in agent restrictions above, and removed Devan's response from last year. Hopefully that will make things more clear (and provide some guidance on how you can add agents to groups).
I am attempting my first bulk import of end-user data. The organization and some end-users exist. The original bulk edit was done b/4 I arrived on the scene and the person is long retired.
Here are my questions:
Do the CSV fields have to be in the order listed in this article or just be present somewhere in the CSV?
Can the header row have initial caps or must it be in lowercase?
To allay my manager's concern: The import will affect only the organizations and users in the CSV file, correct?
Thank you for contacting Zendesk!
We have tested this and it looks like the order of the columns doesn't matter, specifically, when we switched the Notes and email columns and didn't have any issues with the import. So as long as the required columns are included, it doesn't look like it'll matter the order of the columns.
Additionally, our Notes column had a capitalized "n" in "Notes" and that didn't affect anything either. So that could mean the headers can have capitalization :)
For the third question, the answer is yes, the import of the organizations and users should only affect those listed in the file. This is assuming you're importing NEW data and not updating data. So for example, if you already have 100 users and 5 organizations, importing 5 new users won't have and affect on the existing 100. If you update the 5 existing organizations however, then this may affect any linked users that were linked to those existing orgs that were then updated.
Hope this answers your questions! Let me know if you'd like clarification on any of the above information.
Sonny,
Thank you and Happy New Year!
Mark
Seriously,
Please update your guys support. I spent over 20 minutes following the bottom and to do this, it was under settings - then customers. Not what this says below.
To prevent the welcome email message being sent to users
Thanks for the info.
Hi Zendesk,
I uploaded a CSV to add end-users and it was uploaded successfully.
Part of the CSV was the phone numbers- added the international prefix, but when going through the users it looks like the number wasn't added.
What could be the problem?
Hi Danielle
I created a ticket for your use case so we can further investigate your issue. Please check your email and we can start working on this together. Thank you!
Hi
Is it possibile update tickets fields in the same way ?
Hi,
We're planning to switch to Zendesk from another customer support tool. What is the best way to import all customer conversations? I don't think the bulk import would work for this...
Thanks!
The best option to update bulk tickets were indicated in Managing tickets in bulk.
@Irena,
Thank you for considering using Zendesk. Migrating information to Zendesk needs a lot of preparation. We have all the options for migration in How can I migrate information from another platform into Zendesk? We also have our Zendesk Partners to help you with the entire migration process.
Hope this helps!
Hi there - we are using bulk import to import a user attached to multiple companies.
We have Enterprise version of Zendesk.
However when using bulk import it's giving this error:
Multiple organizations were provided. Only one or none is accepted.
From what I can tell the file is formatted correctly?
We will most likely need to take a look at the file you're referencing to see what is happening here.
Can you try contacting our Customer Care team via the method shared in this article: Contacting Zendesk Customer Support
Let me know if you have any other questions in the meantime!
Hi,
I am updating users with new emails because we changed domain name and it's working lik a charm. What about usernames with letters like é, à, ça inside? I have a user named Gaétan in our tests. How can I parse him in the CSV file?
Oh and each have now a new email adress. currently it's @csdps.qc.ca their primary. How can I make the new @cssps.gouv.qc.ca as the primary? Even if it's first in the list, it only adds it as secondary.
If I import users' emails with the domain of an existing organization, will they automatically be assigned to that org? (It would be helpful to have a note about this included above.)
Is there a way to export all the users and modify the file for reimport? We are changing our domain name this weekend, I don't want to change all emails manually.
I'm afraid there's no native option for exporting a CSV file of all end users unless you have the have the Legacy add-on Customer Lists. You can check out this comment by one of our Community Manager in another thread about the available export options for user data. You may export the data in JSON or XML and convert the data to CSV, and then edit the CSV file to match the sample CSV for user import.
For updating users, the identifier is email. If you have an external_id for your users, then you can also use that as identifier.
Please sign in to leave a comment.