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. SeeImporting users with the Zendesk APIorImporting 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. SeeImporting 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 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, seeUpdating existing user profile data.
- 添加换行符笔记或多行自定义字段s 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. SeeAssigning 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 enableInclude external ID in CSV output file、外部id被排除在CSV进口稀土sults file (seeImporting 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 standardizedE.164format. |
| shared_phone_number | If this is a shared phone number, set to "true". A shared phone number cannot be used as auser 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 userswhen 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. SeeAssigning an agent to an Enterprise agent rolebelow. |
| 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 (seeImporting users into multiple organizations). |
| tags | When user and organization tagging has been enabled for Zendesk Support (see seeAdding 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, usemydomainand notmydomain.zendesk.com. |
| custom_fields. |
When you perform a bulk user import, you can import a custom user field by specifying thecustom_fields.prefix and the field key. For example, for the field keysubscription_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. 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. |
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
- InAdmin Center, click
Peoplein the sidebar, then selectConfiguration > End users. - In theUser welcome emailsection, deselectAlso 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. - ClickSave 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 Defaultendpoint.
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 youcreated 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 therestriction 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
可以导入新用户或更新信息existing users.
- InAdmin Center, clickPeoplein the sidebar, then selectBulk 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. 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, seeUpdating existing user profile data.
Note:TheSend email notification to users if their password is changedoption is not currently available.
- (Optional) SelectInclude 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 CSVimport 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 whetherInclude external ID in CSV output filewas enabled.
If you don’t enableInclude external ID in CSV output file、外部id被排除在CSV进口稀土sults 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 clickChoose Fileor theLet me paste in data insteadlink.
- ClickImport.
Your import is added to the queue and the users are added to Zendesk Support when the import process is complete. SeeLimitations of bulk importing users and organizations. You'll receive an email when the import is complete.
Updating existing user profile data
When doing a bulk import, you can choose to update existing users, which allows you to update the user profile data of users that you've already added. Be aware, however, that some of the data isreplacedand some of the data is justappendedto the existing 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)
48 Comments
We were able to add a secondary email for everyone. Now my question is... Is there a method with that CSV to first remove all emails from our users and then import a new primary address?
We did add a new email but the problem is that email is not verified to all our users.
If it's possible then I will do that by evening.
Both importing users via CSV or updating users in bulk via API will add new email address as secondary one. As it turns out, there isn't any native tool that would allow you to easily change the primary email addresses for the users in a bulk.
As a workaround, you could create a custom script that uses our APIs in order to change the primary address:
- Email addresses for the users are stored as identities. First, your script would need to callList Identitiesendpoint - it will return the user_identity id for a particular user.
- After this you would need to callMake Identity Primaryendpoint in order to make the identity (ID from the point#1) primary.
This is definitely one feature that is practical to have. Would it be possible if you can post this in our Product Feedback discussionhereto engage with other users who have similar needs and discuss possible workarounds. Conversations with a high level of engagement ultimately get flagged for product managers to review when they go through roadmap planning. Thank you!Okay I see. Our government forced us to change all emails addresses in our place and many other. The @ and following changed and there is no method to change it easily. We pay tons of money to Zendesk. This is sad to ear.
Hello All,
We have a wonderful appGDPR Compliancethat manages Customers and Organisations.
Hi there! I was hoping for some information regarding importing via .csv, specifically.
I create my list in Excel and format everything as it should be (I am only importing names, organization, email, and phone). I save my spreadsheet using the required UTF-8 character encoding.
Before importing the .csv file in the Admin portal, I open the file to verify the contents I am going to import. When I open this, the "phone" column is missing the required internationally standardized E.164 format (+). This is preventing any phone numbers from being imported; potentially causing duplicates in Support.
Here is my question: how can I keep the required international standardized formatting while also saving it as the required UTF-8 character encoding?
Hello,
We are a global company and in our company the default value on end-users for language is "English" and for Time zone is "GMT +01:00":
Our company has bought a new company in a different region and we are now in the process of replacing their existing support tool and migrating it to our global support platform based on Zendesk.
For this we have the need to set the language as well as the timezone during the import, because the default values are not applicable for the new users.
It seems that currently you can't define language and timezone during bulk import unfortunately - are there any plans for this to be supported in the near future?
If not, what other options/workarounds are there?
Josef Prandstetter
We can help you with the data migration.
Here is our listing//www.ying8.net/marketplace/apps/support/120364/help-desk-migration/
Dima Lazarchuk: you could/should know we are using your services for ticket migration multiple times so far ;) and we will use it in the future as well, because your services are part of our processes to onboard new entities - withmy postswe want to state that we want to see the functionality to set language and time zone in the standard functionality without using a third-party app/service.
Is it possible to bulk import Contributor users? I can find no reference to this in any of the information above - only "End-user", "Agent", or "Admin" roles are mentioned. I have tried importing with the role set to 'Contributor' but this defaults to End-user when viewing the user in support. I am able to create a Contributor user manually, so I don't think it's an account restriction.
Unfortunately, it is not possible to bulk import users with Contributor as their role. This is due to limited permissions in this role, you can only manually change the user role after they're imported to your account as end-users. Thanks!
Hi,
i have a question, i want to create new users via the bulk importing method,
I see the fields: name, email etc....
does the external_id is option or required field?
if it is required field how do i get them if I insert new users?
It is optional. As per the article:
"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 . External IDs must be unique for each user, or data will be overwritten.
If you don’t enableInclude external ID in CSV output file、外部id被排除在CSV进口稀土sults file (seeImporting the CSV user data file)."
BTW, "Include external ID in CSV output file" is now called "Include external IDs in import results file".
If you have to use an external_id, activateInclude external IDs in import results filewhen doing a bulk import. Someone at your organization should know if external IDs are used to identify users in addition to the users' email addresses.
Personally, I have not included external IDs and everything is OK with bulk imports if users.
hello,
is there any empty template available. available?
thanks
Hello,
Is it possible to use the "Bulk import users" feature to suspend existing users? Is there a column I could include in the CSV file? I tried adding the "suspended" column with the value of "true", however, it didn't suspend the user.
Thank you,
Valeriia
In all the documentation, I do not see it listed that you can bulk offboard Agents as well. It could be implied except that there is a specific checkbox needed to be selected in order to do so (i tried uploading an image but get an error that it is too big even though it is 35kb and way under 2mb)
If you go to the bottom part of the article, it will provide you the default file. It will also be advisable to do a one time export of your users so that you can have all the values for your user info.
Hi Valeriia,
I have tried it on my end and the actual bulk import option does not support suspending users. I even tried to export a suspended user but it does not have the information that it is suspended. The only option is to use theUser Update APIand set the suspended attribute to "true".
Is there a way to include a password during the bulk upload? As an admin I find it very tedious to edit users one by one because we want them all to have a certain password.
Unfortunately, we don't have that option for bulk import. You can look into the option of leveraging theUser Password API.
Pleasesign into leave a comment.