Bulk importing users and organizations Follow

all plans

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 add new users, replace existing user information data, add organizations, or replace existing organization data.

You must be an administrator to bulk import users and organizations.

Note: 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 user data described in the table below (Creating the CSV user import data file); however you cannot import the user's time zone, or photo, or language preference, etc. To import that data, you need to use the Zendesk REST API instead. See Importing users with the Zendesk API.

There are also the following limitations to bulk importing:
  • 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 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 organization data file

If you use organizations in Zendesk Support, you can bulk import a list of organizations using a CSV file. You must import the organizations before you import the users that will be added to them.

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 any existing data for that user.
Note: Microsoft Excel cannot save your file directly. 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.
Table 1. Organization import data
Field Description
name Required. The organization name.
external_id If you have a uniquely identifying ID, other than the organization's name, you can include it here.
notes Notes about the organization. Notes are visible to agents only, not to end-users.
details Detailed information about the organization, such as the address. This information is visible to agents only, not to end-users.
default This is for mapping users to an organization. Enter one or more email domains, separated with spaces.

See Automatically adding users to organizations based on their email domain.

shared True or False. Sets the organization as a shared organization.

See Setting up a shared organization for end-users.

shared_comments True or False. Allows all users in the organization to add comments to each other's tickets. The shared field must also be set to true.

See Setting up a shared organization for end-users.

group Enter a default group for the organization. See Mapping a group to an organization.
tags When user and organization tagging has been enabled for Zendesk Support (see Adding tags and users to organizations), you can add tags to the organization. Separate each tag with the comma.
custom_fields.<field key> When you perform a bulk organization import, you can import a custom organization 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: To locate the key for a custom org field, click the Admin icon () and select Organization Fields, then click the name of a 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. 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.

See Adding custom fields to organizations.

Importing the CSV organization data file

You can import new organizations or update information for existing organizations.

To import the CSV organization data
  1. Click the Admin icon () in the sidebar, then select People.
  2. Select Bulk Organization Import (located in the right column).
  3. Choose the type of import you want:
    • Create new organizations
    • Update existing organizations
      Important: Update actually means replace. In other words, if you select Update existing organizations, it replaces the existing data for the listed organizations 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 organization.
  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 organizations 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.

Creating the CSV user data file

When you create a list of users to add to your Zendesk, 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 any existing data for that user.
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.
Table 2. User import data
Field Description
name Required. User's full name.
email Required. 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.
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.
role Case sensitive: "End-user", "Agent", or "Admin". If you don't set a role, the user is set to end-user.
restriction Required when the user's role is set to agent. Restriction sets the agent's privileges, the tickets they have access to, etc.
You can enter one of the following values:
  • assigned, which means tickets assigned to this agent only
  • groups, which means tickets within this agent's groups(s)
  • none, which means that they have no restriction and can access all tickets
  • organization, which means tickets requested by users in this agent's organization
  • requested, which means their own tickets (the agent is the requester)

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.
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: To locate the key for a custom user field, click the Admin icon () and select User Fields, then click the name of a 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. 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.

See Adding custom fields to users.

A note about welcome email sent to users in a bulk import

When you add new users to your Zendesk 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 to your Zendesk. You can prevent the welcome email from being sent to all these users by updating the welcome email setting.

Note: If you started using Zendesk on or after August 21, 2013, welcome emails are not sent to end-users until you activate the Help Center. See Getting started with Help Center.

To prevent the welcome email message being sent to users

  1. Click the Admin icon () in the sidebar, then select Settings > Customers.
  2. In the User welcome email section, uncheck Also send a verification email when a new user is created by an agent or administrator.

    Note: If you started using Zendesk on or after August 21, 2013, this option is not available until you activate the Help Center.
  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,"venticello@somecompany.com",,,,,,,Organization1|Organization2|Organization3,,

If you list an organization that does not exist in Zendesk Support 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 agent role

In the Enterprise version of Zendesk Support, you can assign your agent users 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.

To set a custom agent role, you set the user's role to agent and then use the name of the role as the restriction value. For example, you can set an agent to any of the following five predefined agent roles:

  • Admin
  • Advisor
  • Light Agent
  • Staff
  • Team Leader

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.

Note: In the Enterprise version of Zendesk Support, agent roles override the standard agent restrictions. This means that you can't use any of the standard restrictions listed in the table above. You must use an agent role. If you try to import or update an agent user with the standard restrictions (for example, "assigned"), the agent is set to Light Agent.

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

To import the CSV user data
  1. Click the Admin icon () in the sidebar, then select People.
  2. Select Bulk User Import (located in the right column).
  3. 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.
  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

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 Zendesk 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)
Have more questions? Submit a request

Comments

  • 0

    Is there any way to set a primary and secondary email address on bulk import? I had to put together a support process for a specific internal request so it should have been easy but my company uses two sets of email aliases...so I have 120 people who belong to an Org with only one of their aliases associated with their end-user profile. I'd like to add the second alias for these 120 end-users en masse. Is this possible?

    I've already tried separating the email addresses in the email field with a comma and with a pipe delimitter. Also, I can't use the email domains on the Org level because I don't want all company employees to be a part of this Zendesk Org as its members represent only a subset of employees at my company.

    Edited by Rich Lorenzo
  • 0

    @Rich,
    You'll need to update existing users with an external ID in order to append an additional email to the profile. I've attached an example of what you'd need to upload in order to add a secondary email to an existing user.


    Please let us know if that causes any complications!

  • 0

    @Justin - that's super useful information! Thanks.

  • 0

    Thank you Justin! This worked like a charm!

    And for anybody else that might need to do this...it might be obvious to you from the start but I didn't realize it until I really got into it...you don't have to have each user record next to each other like in the screen shot example. I think it was like that more to demonstrate how to make this work.

    So on mine I did external ID 1-74 for the Original import list (with the existing email alias) and then started over on the same sheet going from 1-74 again with the new email alias. This made it very simple since I still had the original import list saved.

    And if you put any notes you only have to have it once otherwise it will post to user record twice. That was something I didn't catch until I did the import.

    Edited by Rich Lorenzo
  • 0

    Hi

    When bulk updating users, what is the "link" / "primary key" of a user account? The e-mail address? How can we be sure that the login information of user X isn't passed on to user Y?

    Thx

  • 0

    Hi Kris!

    The email address is the primary piece of information used to identify users in your Zendesk. As long as your CSV is properly formatted, your information will import without a problem.

  • 0

    Is it necessary to import both together ? (users and organization)

  • 0

    @Luca, no. However when importing the users you can specify the organization therefore the organization really needs to be there first.

  • 0

    For an Organization upload, this document says, "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"

    However, the list of fields for an Organization upload do not include "id". So, when I'm uploading a list of organizations that are going to be replacing my existing organizations, how does Zendesk know which organizations I'm replacing? Does it simply match them on Organization Name?

  • 0

    Hey Seth,

    Great question! I had to reach out to a few team members to find the answer, and it stumped a few! But I did find the answer!

    EDIT(bad info I needed to correct!): Organization fields will be matched up by the unique name. This is what will determine if something is merged with old information or not.

    Thanks for the great question.

  • 0

    Hi Ryan,
    Your source must have been thinking of Users. The fields listed in this article under "Creating the CSV organization data file" do not include an "email" field.

  • 0

    For organizations the name is unique and used to match.

  • 0

    Thank you, Colin!

  • 0

    Thanks Seth and Colin for the correction. I edited my original response to reflect as much (and also received a second opinion).

    Thanks guys!

  • 0

    Unfortunately -- and correct me if I'm wrong -- but this ultimately means that I can't use this feature. I'm trying to use the bulk update to update the names of my Organizations (so that they match our Salesforce Account names, which is required for Zendesk's integration with Salesforce).

  • 1

    Hey Seth -

    Unfortunately, you're correct - given that they match based off of org name there is no way to update the names themselves with this feature. I would recommend our Organizations Endpoint from the good ol' API - these key off of an Organization ID rather than the name.

    Specifically - you could use the List Organizations endpoint to get the Names & IDs of all of the orgs in your Zendesk, then use the Update Many Organizations endpoint (along with the relevant Org IDs from the previous step) to update all the orgs with their new names.

    I hope this helps - sorry for any confusion so far! To reiterate, bulk updating organization names needs to be done through the API as opposed to the bulk organization upload.

    If you have any questions just drop us a line at support@zendesk.com and we'll be happy to help.

  • 0

    A helpful article that goes through getting around UTF-8 error when bulk uploading users: How to fix the UTF-8 error when bulk uploading users

  • 0

    How do I set a custom checkbox in the user profile as "checked"? I've got the custom user field listed correctly in the .csv file but no matter what data I put in, it doesn't check the box during the bulk import. 

  • 0

    @Brad

    You've probably done this but have you tried a 1 for "true"? That's usually how that works but I've never needed to do this in Zendesk.

  • 0

    @Rich I just tried that and unfortunately it didn't work. 

  • 1

    Would it be possible to put some of the tips, for things like multiple emails per account, in the actual article so that people do not have to scroll through pages of comments looking for clarification? 

  • 0

    @Helen +99

    IMO this should be standard for all articles as new details emerge.

  • 0

    @Helen & Jonathan - Thank you for bringing this to our attention! I have reached out to our Documentation team so that they can update this article with the new information that's been presented in the comments.

  • 1

    There are a lot of comments on this article so this tip may end up getting buried but hopefully it will help others.

    I was doing a bulk org import and was trying to set the org's group. After help from the Zendesk Support team I found out that the group field should be the group name, in all caps. In my case the group was 'Tier 2' so I had to put 'TIER 2' in the group field.

    Edited by Rachel Wolthuis
  • 0

    I'm having trouble setting the default organization for users who belong to multiple organizations. I use the method described in the directions with the pipe delimiter but no matter how I arrange the orgs, the one that comes first alphabetically ends up as the default org. What I really want is another org to be the default. Does anyone know how to set the default org in a bulk CSV user import?

  • 0

    @Justin - That's expected with the bulk import. It's going to apply the default to the first org alphabetically. Your best bet for setting default orgs in bulk is this API endpoint. 

    I'm going to send a note to our docs team about adding a note to this article clarifying the expected behavior.

  • 1

    Can we use the External ID as the field to match records with in SFDC?  Matching only on Account Name is incredibly limiting.  Who has a CRM with no duplicate account names in it?!  Not I.  :-)  Let me know if I can match on External ID instead.  This is for matching Organizations with Accounts.

  • 0

    And is this still limited to 2000 rows?  We have 250,000 plus Organizations we would want to import.  How do we go about doing that besides a ton of small files with 2000 records at a time?

    Can we just have SFDC sync everything over?

  • 0

    Can I bulk upload tickets from our old ticketing system to Zendesk?  We are using Desk.com. I'd like to export all of them and import them into Zendesk so our history is maintained.  Is that possible?

  • 0

    I'm prepping a bulk upload file and realizing that there isn't a field for brand listed above. Will the system ask me on upload, or is it going to select a random brand to send the invite from? 

Please sign in to leave a comment.

Powered by Zendesk