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. Bulk import via a CSV file only works for Support users and roles.
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 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.
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.
Note: 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 their email address), you still need to include the email field in the CSV file, even though it would contain no data. For example:
|
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 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 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
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 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've 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
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 (and all the ticket 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 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: Use this type of import to replace existing data for the users listed 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. For a list of exceptions, see Updating existing user profile data.
-
- (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
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)
131 Comments
Hey Everyone!
I would like to prioritize our key organizations, however, I don't have the full email of every single contact that we deal with within each company. However, I do have the domains...Does anyone have experience with this or know if it is possible without the full email address?
For example: all created tickets with '@apple.com'
would be prioritized to our Premium Support Group?
Hi Anne!
This seems to not be related to the Bulk Import, but I believe I have a solution for you.
If these users are all part of the same organization in your Zendesk (lets say, Apple) you can open the profile page for the organization Apple in your Zendesk and add a tag to it. That way, all the tickets created by users in this organization will also have that tag. You can then create a trigger that all tickets with that tag will be put under the group Premium Support. You can check more details about this workflow below
https://support.zendesk.com/hc/en-us/articles/203662006-Adding-tags-to-users-and-organizations
Hope this helps!
Whenever I try to create new end-users in my organization, my bulk sheet ends up creating each person AS an organization...what am I doing wrong? I fill out the person's name, their email, set their role as "End-user" and their organization as "East", but then each person becomes an organization and not an End User.
Hey Grace!
That shouldn't be happening if you're selecting Bulk user import and not Bulk organization import! I'm going to create a ticket for you so we can investigate this further so please keep an eye out in your email - thanks!
Hi,
Is there a bulk update to verify all (or a subset) users' identities? Or do we have to create a script to make a put request on `PUT /api/v2/users/{user_id}/identities/{id}/verify` endpoint, given a list of users identities?
Thanks,
Felipe
Hello Felipe,
I am afraid that there is no way to bulk verify identities, the reason for this is that the moment in order to update a user's identity you need to specify the ID.
Hi, is it possible to include a timezone column in the bulk import template? Thanks!
Hey Nicki! Welcome to the Community!
It's not possible to include the timezone on the CSV template; only certain fields can be imported via this method, as listed above.
However, you can include the time zone, as well as lots of other information, if you do your import via API. You can find the information on this here. Hope that helps!
The easiest way to import users is to use the automated service - Help Desk Migration
I have bulk imported from our Active Directory and when using the Microsoft sign-in feature, all new users that were created in the import (and in general if I create a new user) gets an error when logging in. Microsoft will accept their credentials, but when directing back to Zendesk, there is an unverified error that will not allow them to login.
Hi we have bulk imported users from an old zendesk instance into a new one but they are all with the role "agent" and we need them to be "staff" in order to link them to the tickets we intend to import next. We tried to bulk change the new users to "Staff" but we get this error:
Hi James,
Thanks for your question and sorry you're having trouble with the transition from your old Zendesk to the new one.
When users are listed as "staff" in a Zendesk instance, it requires the same kind of "seat" as is required for an agent. This is why you're receiving the error code you are.
What you could potentially do is bulk import the users as "end users" - however, this limits the kind of "linking" at your disposal. In other words, you couldn't link an end user as the "assignee" on a ticket but you could have them as the requester or have them CC'ed on the ticket.
This article gives an account of how roles are determined within Support.
Hopefully this clears things up!
You can use this instruction for import (migrate) your csv data into Zendesk
https://github.com/HelpDeskMigration/zendesk-import
Hi, i have a question.
The API method can be used to UPDATE existing users?
Thank you!
Hi Diego,
Yes, you can use the API to update your existing users. More info on that here: https://developer.zendesk.com/rest_api/docs/core/users#update-user
Thanks for your question
Question - I have turned off the welcome email, so the stores (end-users, but going to make them light agents) don't get that prompt - to login. Which I don't want them to be able to do yet. Although, say with the internal guide feature - them as light agents, will be able to access that.
Can I trigger that welcome email, if I update the stores again? If I wanted to - by turning that on? They will already be light agents though, so won't get it regardless? Given they're not "new" but being updated?
Is there anyway I can down the track - trigger a 'welcome - setup your password etc.' email in BULK? Or mass password resets for accounts, so they get that email?
Cheers
Hi there!
I'm trying to bulk import and when I click the "Bulk user import" link in the settings/people section, it just leads me to a blank page.
This article mentions that you need to be an administrator to bulk import and I am, and I am also on a paid plan. Is there a glitch or is there something else I need to be doing to be able to bulk import?
I am trying to add phone numbers to our existing users because we are implementing Talk. I do not want to add new users. If I bulk import a CSV that just has emails and phone numbers, will this just update existing users, using email as the primary key. Or will it also add new users for any email that is not found in our ZD database currently? I am not including name and restrictions columns in the CSV file, so I am thinking it will not add new users without these required fields. But I want to confirm.
Also, if an import does not work correctly, is it reversible?
Hello Michael,
Thanks for reaching out!
So first things first, the CSV upload requires the name and restrictions fields be present; excluding these columns from the upload file will error out. So you would need to include these fields for the file to take.
One thing you can do is export out the users that are already in the system and then upload a file with all the necessary fields (as well as the additional phone number field) back into Zendesk to update their user, accordingly.
As a heads up, when adding numbers to users, be sure to adhere to the correct formatting when inputing the number. You can find more information on the proper number formatting in the following document:
https://support.zendesk.com/hc/en-us/articles/115003671888-What-are-the-accepted-phone-number-formats-for-Talk-
To answer your question, barring an erroneous attempt to import a user without the appropriate required fields, Zendesk will create a new user for any email address that is not currently in the system. Attempting to add the same email address for a new user would not successfully create a user, as any given email address can only be associated with one user in the Zendesk instance in question. If you were to attempt to update a user and referenced an email address in the respective column of a CSV upload file, whatever values you enter (or don't enter but leave blank) will update that user, accordingly.
Lastly, if an import isn't done correctly, it won't take in the system. So yes, it would be reversible in that nothing would happen within Zendesk; the file would be rejected.
I hope this proves useful in your efforts!
I am trying to import 20 agents using the Bulk user import link. When I click the link, the screen basically goes blank. It does not give me any options to upload my file. I can manually load, but would love to have the option to upload since I will need to add about 300 agents in a couple of months. Can you please check this out for me.
Hi Shannon!
For security purposes, I'm going to move this into a ticket so that we can discuss this. I'll reach out to your shortly!
We have two brands with common customers with different member numbers/ policy number. Is it possible to add two external numbers for one customer?
Hey Alice,
Just to confirm, is this a custom field you've created to add your members number/policy numbers to? Or is this the External ID field you're attempting to have multiple numbers set up for? If so, I'm afraid each user can only have one external number set up on their profile.
You'd most likely need to create a custom numeric field to include these different member policies on the users profile. I've attached the following documentation for Adding custom fields to users which I believe you'll find useful.
Let us know if you have any other questions
Thanks Brett. We've added a custom field and would like to import numbers to fill this field during the bulk upload. Is it possible?
Hi Alice,
That's certainly possible by using the custom_fields.<field key> when you bulk import. If you're using a numeric field you'll need to set up a separate user field and then include those in the CSV file you intend to import. If you're unsure of where to locate the custom field you can take a look at our Identifying field keys for custom fields article which I've attached.
Hope this points you in the right direction!
Hello,
I'm having the same problem as Shannon Greene. When I try to bulk import users, it just goes to a blank screen. I've tried a few browsers and am getting the same result. Any help would be greatly appreciated as I have over 1200 end users to load up.
Thanks!
Hi there,
Is any one able to help? I haven't heard back yet and I really need to get this set up.
Thanks!
Hi. I am trying to upload users in bulk and when i press the button on the top right of the people page to do this, it goes to a blank screen. I am on a team plan for Zendesk support and as per your policies, it should work. Please help.
Hi Lisa and Winnie, I have created a ticket for each of you and will reply to both of you on the respective tickets.
Hi,
I am having the same issue stated by Winnie, Maddie, Lisa & Shannon. We currently have Support Team plan and I am an Admin but cannot access the Bulk User Import section. When clicking the link I receive a blank page. Any assistance would be greatly appreciated.
Thanks!
Please sign in to leave a comment.