Bulk importing users and organizations

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.

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 Zendesk REST API: Introduction).

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.

Creating the CSV organization data file

If you use organizations in your Zendesk, 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.

The first row of the file is the header row and contains the fields listed in the table below. You must include the header row, using all the fields and in the order they are listed below, even if you're not importing that data. In other words, you can have empty columns of data, but you must include all the header row fields.

The file must be properly formatted CSV and saved using UTF-8 character encoding.

The following table lists the fields that you can include in the file.
Table 1. Organization import data
FieldDescription
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 in Creating, managing, and using organizations.

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

See Shared organization for end-users in Creating, managing, and using organizations.

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 Shared organization for end-users in Creating, managing, and using organizations.

group Enter a default group for the organization. See Mapping a group to an organization in Creating, managing, and using organizations.
tags When user and organization tagging has been enabled for your Zendesk (see Adding tags to users and 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.

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.
    Zendesk Classic: Select the Manage menu, 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
      Note: Warning! Currently, 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. If you want to add some additional organization data after you've added the organizations to your Zendesk, your CSV file must also contain all the original data from the initial bulk import plus the new data.
  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 your Zendesk 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.

The first row of the file is the header row and contains the fields listed in the table below. You must include the header row, using all the fields and in the order they are listed below, even if you're not importing that data. In other words, you can have empty columns of data, but you must include all the header row fields.

The file must be properly formatted CSV and saved using UTF-8 character encoding.

The following table lists the fields that you can include in the file.
Table 2. User import data
FieldDescription
name Required. User's full name.
email Required. User's full email address (someuser@mycompany.com).
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 number.
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, 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 Plus 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 your Zendesk (see Adding tags to users and 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.

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 the Help Center.

To prevent the welcome email message being sent to users

  1. Click the Admin icon () in the sidebar, then select Settings > Customers.
    Zendesk Classic: Select the Settings menu, then select End-users.
  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 Plus 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 your Zendesk the import will fail.

Assigning an agent to an Enterprise agent role

In the Enterprise version of Zendesk, 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 your Zendesk, 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, 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".

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.
    Zendesk Classic: Select the Manage menu, 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
      Note: Warning! Currently, update actually means replace. In other words, if you select Update existing users, it replaces the existing data for the listed users in your CSV file. If you want to add some additional user data after you've added the users, your CSV file must also contain all the original data from the initial bulk import plus the new data. See Updating existing user profile data below.
  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 your Zendesk 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 your Zendesk. 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
  • phone
  • role
  • restriction
  • organization
  • Custom fields

The following user data is appended (added to the existing data):

  • details
  • notes
  • tags
  • email (added as a secondary email address)
Have more questions? Submit a request

Comments

  • Avatar
    Lauren Parks

    Do users added via bulk import receive an email notification right away of their account?

  • Avatar
    Anton de Young

    Lauren,

    They will receive the email as as soon as the bulk import has been processed and they have been added to your account. 

  • Avatar
    Kelly Hoffer

    This is true as long as under Settings> End-users>

     Also send welcome email when a new user is created by an agent or admin 

     

  • Avatar
    Kevin Foster

    Is there a way to export the existing user list back to a CSV file, make changes to a field (e.g. Organization), and then upload the CSV back and update the existing users?

  • Avatar
    David G

    I have the same question as Kevin.

    We just started using the capabilities of the Organization, and currently most of my users are not assigned to any ORG.

    If i could export the user list, modify it to add them to the proper org, and then re-import it that would be great. We have 1312 end users and i would hate to think we have to do this manually.

     

    Thanks for any reply.

  • Avatar
    Neville Kennerley

    I want to do the same as Kevin and David - how do we do it?

  • Avatar
    Cory Brown

    I have the same question as above as well. Also, can you bulk update tags for Organizations, or is that only for users?

  • Avatar
    Anton de Young

    Kevin, David, Neville, Cory:

    Sorry for the delayed response. We do not currently have an option for exporting your user data as a CSV file. If you're on the Plus+ plan you can download user (and group and organization) data in XML format (Manage > Reporting > Export). However, you'd then have to convert it to CSV. Not an easy thing to do unfortunately. As a test I wrote some XSL to do that but you'd need to be set up to do XML/XSL transformations. After that, you'd need to clean up the file in Excel (or some other spreadsheet application), add your new data, and then import it into your help desk. Possible, but lots of work. I would suggest adding this as a feature request to this forum: https://support.zendesk.com/forums/1848-feature-requests. 

  • Avatar
    Cory Brown

    Thanks Anton. We've since developed a Google spreadsheets solution to update organization tags.

  • Avatar
    Kirk Cohen

    can you provide a template?

  • Avatar
    Pete P

    Hi Anton,

    could you please provide the structure for the user data file on the enterprise plan (light agent, staff, etc.) and enhanced user roles.
    Cheers,
    P!

  • Avatar
    Anjanette Montagnino

    Hi,

    I noticed that it mentions that if I provide a password the end user will not receive the welcome message. What message will they receive? How will they know how to use the support site?

    Thanks,

    Anjanette

  • Avatar
    Max McCal

    If you add passwords to the accounts, users will not be notified. No message will be sent out in this case.

    You can notify them through other means, of course, but generally it's best to leave it blank unless it's an internal user who you maintain. The welcome message can contain any information you like, and it's usually easier to use that messaging to inform customers how to set up their own password than to try setting one for them yourself.

    Thanks!

  • Avatar
    Anton de Young

    Pete P, 

    The enterprise roles aren't supported in the bulk import yet - but they will be soon. For now, in Zendesk Enterprise, the agent users you import will be set to Legacy Agent. You can then manually change them to the other agent roles. 

  • Avatar
    Kevin Kallassy

    Forgive my ignorance, but if I wanted to create the user list in an excel file, do I assume that each cell works in place of the commas?

     

    Thanks in advance,

    Kevin

  • Avatar
    Kevin Kallassy

    I'd like to also add that I have attempted to import a test user with a CSV file and receive an error. It says "Illegal quoting on line 2" I've attached the file that I am using to test.

    Any idea what this means?

     

    Thanks,

    Kevin

  • Avatar
    Anton de Young

    Kevin, 

    Yes, you can create the import file in Excel. You then need to save it as a CSV file, which it looks like you did. However, it's not a valid file. It should be pure text. Try to save it as a CSV file again. After you save it, you should be able to open it in a text editor and just see the data separated by commas. 

  • Avatar
    Kevin Kallassy

    Anton,

    Thansk for all of the help, we've sucessfuly imported users via the CSV file. I have one more question though regarding the details field in the imported file.

    We'd like to have the details formatted correctly in the users profile but we haven't been able to do that yet. We've tried using a few characters (,.;':") but nothinghas worked yet.

    Here's an example, we would like the details box to include an address:

    555 main street

    wherever, IN 12345

    Room 123

     

    When we do a bulk import with our test users, the details box updates with the information, but it ends up looking like this:

    555 main street wherever, IN 12345 Room 123

     

    Is there a character that we can use that will tell zendesk that we want a new line?

     

    Thanks in Advance,

    Kevin

  • Avatar
    Max McCal

    Hi, Kevin -  This took me a bit of digging to find, but it looks like if you're creating a CSV file you can get line breaks if you insert a carriage return. I was able to do this by using Alt + Enter on a PC or Control + Option + Return on a Mac. If the cell actually has a full carriage return that will translate into the notes or details field on your user. Please give it a try and let us know if it works for you.

  • Avatar
    Laura

    @Anton I tried creating a few users using CSV, I want them to be light agents. However since you said they first have to be imported as regular agents, I used "agent" as the role. But I get an error because I am at my max number of agents. Is there a way around this?

  • Avatar
    Anton de Young

    Laura, 

    For now I think you'll need to import them as end-users and then manually change them to light agents. 

  • Avatar
    Laura

    OK, thanks.

  • Avatar
    Anton de Young

    Laura and others, 

    You can now set enterprise agent roles in a bulk import. See Assigning an agent to an Enterprise agent role above.

  • Avatar
    Martin Grøn

    I would like to say +1 to being able to export the user data, make changes to the file and import it again - we do not have API access and more than 800 user, so I dont want to do it manually!

  • Avatar
    Ososoba

    Is it possible to setup CRON jobs in zendesk, so that it imports a CSV file of newly added customers on my online store regularly? And what happens if one of the imported contacts already exists?

  • Avatar
    Clint Wilson

    Very Helpful thread ZD team and just sent to a Zendesk client for test importing today.

    ~Clint

    @cazoomi

  • Avatar
    Owen Pickford

    It's not clear to me from the instructions how an upload will affect a user that is already in ZenDesk.  It seems to me that everything implies the data uploaded will overwrite the data that is already in ZenDesk.   Is this true?   More specifically, if you upload a file with non-required fields left blank will it overwrite information that is already in ZenDesk with the blank field, essentially removing the data in ZenDesk?  

    If this is the case, definitely +1 do exporting data from ZenDesk.

  • Avatar
    Anton de Young

    Owen, 

    Yes, that is currently how it works. See my note in Importing the CSV user data file above. 

  • Avatar
    Kevin Foster

    I found a cheap program to convert the data from XML to CSV.

    http://www.xml-converter.com

    It worked great! Made the process much quicker than dealing with XSLT transformations.

  • Avatar
    Kevin Osburn

    Hi Everyone,

    3 Questions before I do a bulk user upload.

    1) If I choose "Update existing users" for a bulk upload, will all the user's existing tickets remain intact? 

    2) Which field is connected to the user's ticket; name, email or something else? I need to change a few names and emails, but don't want to loose any info.

    3) If I leave the 'password' field blank, will the user be prompted to change his/her password, or does the current one remain intact?

    Thanks ahead of time for any help.

    -Kevin

Please sign in to leave a comment.