Summary: ◀▼
Use a CSV file to bulk create or update Support users instead of adding them one at a time. You can import profile details, roles, agent privileges, organization memberships, and custom user fields. Prepare the file with the required format and identifiers, and review import limits and update behavior: most existing data is replaced, while additional email addresses and phone numbers are appended. Imports require admin access and must be enabled for your account.
Admins can add many users in a bulk import rather than adding users manually one at a time. To do this, you create a comma-separated values (CSV) file that contains the user's data. In addition to essential user data, such as email address and phone number, you can also 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 through a CSV file only works for Support users and roles.
You must be an administrator to bulk import users and organizations.
If you're using the legacy method to import user data through the Bulk actions pages, see Bulk importing user data (legacy).
- To protect the data in your Zendesk account, data imports are not enabled by default. The account owner or an admin must contact Zendesk Customer Support to enable data imports and access to the imports page.
- If you want to bulk import both users and organizations, you must import organizations first.
Considerations for bulk importing users
Limitations for bulk importing with the data importer
You can import a core set of data about users and organizations. To import data not listed in the table below, you must use the Zendesk REST API instead. See Importing users with the Zendesk API.
- When using the data importer, 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.
- The import CSV file can contain a maximum of 200 columns.
- The import CSV file can't guarantee import order for rows.
- Regular expression (Regex) type user fields can't be imported or mapped.
- Don't include the same user or organization more than once within a CSV file. Doing so can cause your import to fail.
- There's no guarantee that records are created or updated in the order they appear in the CSV file.
- 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 the bulk importer 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.
Updating existing user profile data
How data is updated by the data importer
- phones (added as a secondary phone numbers)
- emails (added as a secondary email addresses)
All other data is replaced by the data importer.
Deciding whether to send an email to users imported in bulk
Before you perform a bulk import of users, it's important to check your welcome email settings. When you add new users via a bulk import while Guide is enabled, 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 these users.
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.

- Click Save.
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.
- You can download a CSV template in Admin Center > Data importer > Import > Download a CSV template.
- 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. |
| emails |
Required for importing new users. User's full email
address (someuser@mycompany.com). If including more than one
email address for a user, separate them by a pipe (|). For
example:
first@yourcompany.com|second@yourcompany.com
|
| alias | An alias displayed to end users. |
| brand_id | If the account uses department spaces and
the role is set to agent, include the ID of the
brand the agent should be associated with. |
| custom_role | When the role is set to agent, specify the
custom role name, as listed on the Roles page in Admin
Center. Light agent is also accepted. |
| default_group_id |
New team members (admins and agents) are automatically added to the account's default group. However, you can use this field to specify alternative default groups for users during bulk imports. When you change a user's default group, they will still be a member of their previous groups (including their previous default group). End users can't be added to groups. |
| details | Detailed information concerning this user, such as an address. This information is visible to team members only, not to end users. |
| email_ownership | Applies only when shared end-user email
addresses are turned on. Case sensitive:
Applies only when the email
identity is created, including adding a new address to an
existing user. Doesn't change an email the user already has.
You can't send both |
| email_auto_ownership | Applies only when shared end-user email
addresses are turned on. Boolean. When set to
Applies only
when the email identity is created, including adding a new
address to an existing user. Doesn't change an email the
user already has. You can't send both
|
| 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. |
| locale | The user's locale. A BCP-47 compliant tag for the locale (e.g. en-US). If both locale and locale_id are present, locale_id is ignored and only locale is used. |
| local_id | The user's language identifier. |
| moderator | Boolean. Designates whether the user has forum moderation capabilities. |
| notes | Notes concerning this user. Notes are visible to team members only, not to end users. |
| only_private_comments | Boolean. When set to true, the user can only
create private comments. |
| organizations | 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 plans, you can add a user
to multiple organizations by separating the organization
names with a pipe character. For example:
A user's default organization is set to the first organization alphabetically. It isn't possible to set a different default organization during a bulk import. However, the default organization for a user can be adjusted manually or with the Ticketing API - Set Membership as Default endpoint. |
| phones | The user's telephone numbers. Unique phone numbers are added as direct lines. Phone numbers that already exist are added as secondary lines. If you're including more than one phone number for a user, separate the phone numbers with a pipe (|). To work with Zendesk, phone numbers should be formatted with the internationally standardized E.164 format. |
| remote_photo_url | A URL pointing to the user's profile picture. |
| role | Case sensitive: end-user or
agent. If you don't set a role, the user is
set to agent. |
| shared_phone | The user's shared telephone number. To work with Zendesk, phone numbers should be formatted with the internationally standardized E.164 format. |
| signature | The user's signature. Only agents and admins can have signatures. |
| skip_verify_email | If you need to create users without sending out a verification email, set this value to true. |
| suspended | Boolean. Indicates whether the user is suspended. Tickets from suspended users are also suspended, and these users cannot sign in to the end-user portal. |
| tags | When user and organization tagging has been enabled for Zendesk Support (see Adding tags and users to organizations), you can add user tags. Separate each tag with a comma. |
| ticket_restriction | Restriction sets the team member's or end user's privileges,
the tickets they have access to, and so on. This is required to
import new users when the user's role is set to Agent. On
non-Enterprise plans, the following restriction values are
supported:
Restriction values of
organization
and requested can be assigned when the user's
role is set to end-user. All others apply only
to team members.
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 specify
an agent role. If you accidentally use a role name that
doesn't exist in Support, the user's role defaults to Light
Agent.
|
| time_zone | Consists of a string such as "Eastern Time (US & Canada)". For a list of valid names, view the Time zone list menu on the Localization page (Account > Appearance > Localization) in Admin Center. Example: If the menu lists "(GMT+02:00) Berlin", then use "Berlin" as the time_zone name. |
| 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 custom_fields.subscription_date 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; 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.
|
Using the data importer to import user data
You can use the data importer to import a CSV file that creates or updates existing users, and captures logs of all imports attempted through the Data importer page.
- In Admin Center, click
Objects and rules in the sidebar, then select Tools > Data importer. - Click Import.
- Under Target destination, select Users.
- Under Import type, choose one of the following:
- Create only: Only new users are added. Any data in the CSV file pertaining to existing users is ignored.
- Update only: Update data for the existing users listed in your CSV file.
- Create and update: Add new users and update data for the existing users listed in your CSV file.
Note: If any external ID, email address, or phone number matches more than one existing user, that row is rejected from the bulk import. Check your import history. - Under File upload, drag and drop your file or click to upload
and select your CSV file from the file browser.
If you need to change the file you've selected, click the delete icon (
) next to the file name. - Click Next.
- Review the Field mapping list.
- If the field mapping is correct, click Next.
- If the field mapping isn't correct, click Back. Edit your CSV file to adhere to the format requirements, then reupload the file.
- Review the summary of import details in the confirmation dialog and then
click Start import.
After the import starts, the imported changes can't be reverted. To check the status of an import, check your import history.
Article Q&A
Click to view
What do I need before I can bulk import users, and how do I start the import?
You must be an administrator, and data imports must be enabled. Imports are disabled by default, so the account owner or an admin must contact Zendesk Customer Support to enable them and access the imports page. In Admin Center, go to Objects and rules > Tools > Data importer, click Import, choose Users, select Create only, Update only, or Create and update, then upload the CSV, review field mapping and the summary, and click Start import. If you are importing both users and organizations, import the organizations first. Started imports cannot be reverted.
How do I prepare a CSV file for importing new users?
Use a properly formatted CSV saved in UTF-8, with a header row. Include the required fields and any other fields you want to import, in the order listed in the article; omit fields you are not importing. For new users, name and emails are required, and ticket_restriction is required for users whose role is Agent. You can download a CSV template from the Data importer. Do not include the same user or organization more than once in a file.
What happens when I update existing users with a bulk import?
Include the user's name, email address, or external ID so Zendesk can identify the existing user. With the data importer, email addresses and phone numbers are appended as secondary contacts; all other imported data replaces the existing data. Choose Update only to update existing users, or Create and update to add new users and update existing ones. A row is rejected if its external ID, email address, or phone number matches more than one existing user.
What limits or data restrictions should I know about before importing a CSV?
A CSV can be no larger than 1 GB, contain at most 200 columns, and have rows no larger than 128 KB; Zendesk recommends a maximum of 500,000 rows including the header. Only one CSV can be imported at a time. Import order is not guaranteed, and regular-expression user fields cannot be imported or mapped. The importer supports only a core set of data; use the Zendesk REST API for unsupported data or end-user Facebook and X contact information.
How can I stop new users from receiving a welcome or verification email after a bulk import?
Before importing, go to Admin Center > People > 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,” then click Save. You can also set the CSV field skip_verify_email to true to create users without sending a verification email.