Rather than add users manually one at a time, you 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.
You must be an administrator to bulk import users and organizations. If you are using a trial account, you cannot bulk import users.
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 import CSV data file must contain no more than 2000 rows of data (one row for the header and the rest for the user or organization data).
- You can only import one CSV file of 2000 or less rows of data at a time. Therefore, if you've got more than 1999 users or organizations to import, you need to create separate files for each batch and import them one after another. Up to two batches are queued and run in the background. If you want 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 any existing data for that user.
- 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.
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. |
details | Detailed information concerning this user, e.g. an address. This information is visible to agents only, not to end-users. |
notes | Notes concerning this user. Notes are visible to agents 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. |
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 sets the agent's privileges, the tickets they have access to, etc. Required when importing new users that will be agents.
You can enter one of the following values:
In the Enterprise version of Zendesk Support, you 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 If you are importing information into a checkbox, enter 'true' to have it checked or 'false' to leave it unchecked. Note: To locate the key for a custom user field, click the Admin icon (
![]() 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. For custom date fields, use either the YY/MM/DD or YYYY-MM-DD format. Important: To set the value of drop-down list options, use the tag you added when you created the drop-down list.
|
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. 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
- Click the Admin icon (
) in the sidebar, then select Settings > Customers.
- In the User welcome email section, uncheck 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 (Professional and Enterprise)
If you're on Professional or Enterprise, you can add users to multiple organizations during your bulk import.
To do so, in the organization cell in your CSV user data file, enter multiple organizations separated by a pipe character. For example: 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 theCore API - Set Membership as Default endpoint.
Assigning an agent to an Enterprise custom role (Enterprise only)
On Enterprise, you can assign agents predefined or custom roles (see Custom agent roles). These roles are sets of permissions, not just single permissions as are the standard restrictions listed in the table above.
If you've created your own custom agent roles, you just use the name of your custom role. As an example, here's a CSV example for setting an agent to a role called Help Desk Mastermind.
"name","email","external_id","details","notes","phone","role",
"restriction","organization","tags"
Enrico Venticello,"venticello@somecompany.com",,,,,"agent","Help Desk Mastermind",,
If you accidentally use a role that doesn't exist in Zendesk Support, the agent is set to Light Agent. You can then manually change the agent's role to another role by editing 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
You can assign primary and secondary email addresses and phone numbers to a single user during a bulk import, using the external_id column.
To do this, give the same external ID 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 first of the two email addresses matches an existing user, that user is updated. However, if the second email address matches an existing user as well (the same user associated with the first email address, or a different user), the user associated with the first email address is updated with both email addresses, and the second user errors out, saying that email address already exists.
Importing the CSV user data file
You can import new users or update information for existing users.
- Click the Admin icon (
) in the sidebar, then select People.
- Select Bulk User Import (located in the right column).
- Choose the type of import you want:
- Create new users
- Update existing users
Important: Update actually means replace. In other words, if you select Update existing organizations, it replaces the existing data for the listed users in your CSV file. You only need to include the fields that you want to update in the file. If you have empty columns of data it will overwrite the existing data for that user. Also, see Updating existing user profile data to understand which data is replace and which data is appended when you updated existing 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
As noted above, when doing a bulk import, you can select the Update existing users option, which allows you to update the user profile data of users that you've already added to Support. Be aware, however, that some of the data is replaced and some of the data is just appended to the existing data.
The following user data is replaced:
- name
- external_id
- 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)
118 Comments
There's a typo above: "To to this, give the same external ID"
Hey Jason!
This is actually addressed in one of our Support Tech Notes! There's some good info there, as well as some helpful links: How can I migrate my old tickets and knowledge base to Support?
Hey David! Thanks for the heads-up. I've fixed it. :)
Hey Jason!
The bulk update functionality is still the same - 2000 rows max. If you have that many Orgs to import, I'd recommend pulling them in via API instead. You can find tons of information on this in our Zendesk API Guide.
Hi Shannon!
The system should not require a brand when uploading users. A good way to think about this is brands are associated with tickets, but not with orgs and users. Users cannot be "associated" with a brand therefore there is not a parameter for brand when uploading users.
*Note: You can now specify a brand for users when performing a bulk user upload to send the desired brand's welcome email. (edited 07/2017)
Hi Rebecca,
Brand is relevant, because I need to be able to instruct which Brand url will be in the invite email to the newly created end users.
A prompt for which brand to use upon upload would also be fine. This is how it is handled when you create a single new user.
Hey Shannon -
Understood, thanks for clarifying! :) At this time, this is a limitation with bulk user import and sadly it is not possible to set the brand to then send the brand's welcome email when creating a user. My team has reached out to our Multibrand Product Manager and he is aware of the limitation and has added it to our list of improvements for the multiple brands feature set.
*Note: You can now specify a brand for users when performing a bulk user upload to send the desired brand's welcome email. (edited 07/2017)
When importing an address into the Details field, I'd like to use a carriage return between lines. Is this possible with the CSV bulk import?
Also, it seems to append to the Details when I reimport. Is there a way to replace?
FYI - Excel 2016 has the option to save your CSV as CSV UTF-8 so there is no need to upload to Google Sheets and re-download.
Hi Dan!
Thanks for your question.
I'm pulling this into a ticket, since we may need to look at account information to get you an answer.
Talk soon!
Hi,
It would be great to be able to add a sign "+" for example in the header to REPLACE the value that exists.
for example, we use to upgrade our information, and for customers, we use details and note field to store the contact name or the address, then when we bulk import, it concatened the fileds.
Rule would be : if the header name finish with + sign then replace, otherwise appended.
Best regards.
Hi Sébastien -
Thanks for the feedback! I definitely agree some more explicit method of appending data as opposed to replacing would be helpful! In general, both the notes and details import is not overwritten but instead appended.
Often when users are looking to perform a bulk user update, and do not want to replace existing data we recommend performing a User export under Settings > Manage > Exports. Doing this will give you a CSV of all user data to then make it easier to add updates that append as opposed to replace.
Is there anyway to upload the CSV file via the API? The information captured in our User and Organization fields change quite frequently and we would like to upload a nightly CSV file into ZenDesk to have these fields update automatically.
Greetings Corey,
Thanks for stopping in and leaving us with your question. Unfortunately, you wouldn't be able to send your CSV as a payload. However, you can parse the CSV on your end to create the JSON payload. It will require some doing, but you can definitely check out with these end points (links below) to start off:
https://developer.zendesk.com/rest_api/docs/core/users#update-many-users
https://developer.zendesk.com/rest_api/docs/core/organizations#update-many-organizations
I hope that helps!
Hey all. Is it possible to bulk add users without adding them to organizations?
Hi, we couldn't figure out the format if we would like to bulk upload users by defining the customize roles (enterprise roles) and the groups under restriction. Tried many combinations but couldn't succeed. Zendesk support got back to us as restrictions does not support the groups but article says otherwise. Could you please advise?
Hey Dan!
The only required fields in your user CSV are name and email, if you're importing end users. If you don't want your imported users to be added to an Organization, you can just leave that field off your CSV.
Hey Dilara! Can you give us more specifics about how you're trying to format your document?
Hey team, we have around 200 agents their access must be restricted to the agent group, the problem is we need to add 35 groups. Is there any solution or bulk update includes the groups names ? we won't be able to add 35 groups to around 200 agents. can you please advise ?
Another problem is when creating new accounts with Agent role and restrict the access to tickets in agent group, I need to add these 35 agents and the number may increase, is there any easier way rather than adding them manually, CSV option ?
Welcome to the Community, Lama!
You can use a CSV to bulk update user information, including groups...I think that might be what you're looking for! If I'm missing the mark, though, let me know!
Hey Jessie
The fields in this article include the tickets access restriction type (for me here it is tickets in agent group), but I couldn't not find the field that gives me the option of the addition and the edit of the agent groups and the default group.
Hi Lama, the best way to bulk update multiple agent groups would be via the API. This link refers to associating agents to groups: https://developer.zendesk.com/rest_api/docs/core/group_memberships#bulk-create-memberships
And this doc goes over the link between agents and groups: https://developer.zendesk.com/rest_api/docs/core/group_memberships
Is there a way to import Org Drop-down lists using the Field Title instead of the tag?
Hi Jeff!
If you're going to import using CSC/XML, the information won't import if it's not mapped according to the examples in the article.
However, I believe you can use the API to do a more robust import!
How can I add agents to groups in bulk upload
Hey Moshe!
It's not possible to bulk update a user's group using the bulk upload via CSV, since there's no user data field for it.
However, you can do this via the API. You can find links to the related resources in my colleague Kayla's comment above!
Is there a webservice available for bulk import instead of using .csv files?
Welcome to the Community, Marcello!
If you don't want to use the .CSV method, you can import your users with our API! You can find all of our API documentation here: Core API.
Hope that helps!
We could use to reset every password of our End_Users. I see that with the bulk uploader it says: "
Send email notification to users if their password is changed?
An email notification will be sent to end-users, admins, and agents when their standard password changes. We recommend that you enable this feature.
"
Is this if we ever change their password in the future? We are about to let 2000+ people start using our guides but need to reset all of their passwords before doing so.
Welcome to the Community, Josh!
You're right, as long as the option is enabled in your Zendesk, your users will receive an email notification any time their password is changed or reset. If you'd prefer that this email not be sent for some reason, you can just disable the setting by going to your Gear Icon > Settings > Security > Global tab. Just uncheck the box next to User Email Notification and you'll be all set!
Please sign in to leave a comment.