Bulk importing users

What's my plan?

Quick Look: Admin Center > People > Bulk actions > Import users

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.

Important: To protect the data in your Zendesk account, data imports are not enabled by default in Zendesk accounts. The account owner or admins must contact Zendesk Customer Support to enable data exports and access to the imports page in the account.

Important: If you want to bulk import both users and organizations, you must import organizations first. For information, see Bulk importing organizations.

This article contains the following sections:

• Limitations of bulk importing users and organizations
• Creating the CSV user data file
• Importing the CSV user data file

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.

There are also the following limitations to bulk importing:

• The maximum number of rows depends on the import method.
  • When using the Bulk import pages to import new and existing user and 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.
  • When using the data importer (beta) to import new and existing organization data, 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 X (formerly 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.

Here are some important things to keep in mind when creating your file:

• 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.

Note: MSV excel cannot save your file immediately. To save your file, upload it to Google Sheets, re-download it, and then upload to Zendesk. You can also use Open Office to save the file.

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).

Table 1. User import data

Field	Description
name	Required for importing new users. User's full name.
email	Required for importing new users. User's full email address ([e-mail]). 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: assigned, which means tickets assigned to this team member only groups, which means tickets within this team member's group(s). Note: To add a team member to a group, see Adding and removing team members from groups or use the Support API. none, which means that they have no restriction and can access all tickets organization, which means tickets requested by users in the end user's or team member's organization requested, which means their own tickets (the end user or the team member is the requester) Light Agent, which means the user is given the same restrictions as a light agent (see About light agent permissions). 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: In Admin Center, click People in the sidebar, then select Configuration > User fields.Then click the name of the custom field. The field key appears in the properties panel on the right. 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; for a custom object record, enter the record's ID. To find an organization, user, or custom object record ID, you can export data from your account or use the Organizations API, Users API, or Custom Object Records 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

1. In Admin Center, click People in the sidebar, then select Configuration > End users.
2. 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.
3. 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,"[e-mail]",,,,,,,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,"[e-mail]",,,,,"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.

Note: 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 use an agent role.

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.

Note: The Update existing users check box must be selected.

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.

To import the CSV user data

1. In Admin Center, click People in the sidebar, then select Bulk actions > Import users.
2. 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.
3. (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.

4. Either click Choose File or the Let me paste in data instead link.
5. 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

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 is replaced and some of the data is just appended to the existing data.

Note: To update an existing user, the CSV file must include the user's external_id or email address so that Zendesk can identify the user.

The following user data is replaced:

• name
• external_id
  Note: 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)