Bulk importing organizations

Attention: The data importer is currently in an open beta. The Import organizations page in Admin Center will continue to be available during this beta.

Rather than add organizations one at a time, you can bulk add several organizations by importing a CSV (comma separated values) file. You can use bulk import to add organizations or update organizations. You must be an administrator to bulk import organizations. You can add or update several users at once (see Bulk importing users).

Note: If you would like to bulk import both organizations and users, you must bulk import organizations first. For information on bulk importing users, see Bulk importing users.

Bulk importing organizations can't be undone. Before importing the CSV file that contains the information of all your organizations, test that same CSV file with a single organization record to make sure the upload works as intended.

This article contains the following sections:

• Limitations of bulk importing users and organizations
• Creating the CSV organization data file
• Importing the CSV organization 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.
  • For user data and updating existing 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.
  • For new organization data using the data importer (beta), 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 organization data file

To bulk import organizations, you will use a CSV organization data file. This section will discuss how to set up your CSV data file.

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.
• 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.
• 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 organization.
• Add line breaks to notes or multiline custom fields by pressing ALT+ENTER on Windows or CTRL+OPTION+RETURN on macOS.

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	Optional, but recommended; required if you intend to use the data importer to update these records in the future. A uniquely identifying value, such as an employee or customer identifying number in an external system.
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 (for example, organization1.com organization2.com). 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 set tags for the organization. Separate each tag with spaces. When you bulk import orgs, the tags in your CSV file replace the existing org tags. To avoid this from happening, consider using the Tags API to update tags instead.
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 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. For checkbox fields, use either True or False. To set the value of drop-down list options, use the tag you added when you created the drop-down list. Note: If the custom organization 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. To find an organization or user ID, export data from your account or use the Organizations API or Users API. Lookup relationship fields aren't supported when importing organizations on the data importer page. See Adding custom fields to organizations.

Importing the CSV organization data file

You can use a bulk import to create new organizations or update information for existing organizations.

Your import is added to the queue, and the organizations are added to Zendesk Support when the import process is complete. This should take around an hour per file to complete, but it does depend on file size and queue size. See Limitations of bulk importing users and organizations.

Using the data importer to create new organizations (beta)

The data importer is in a beta release. You can use it to import a CSV file that creates new organizations and capture logs of all attempted imports through the Data importer page. During the beta, the data importer can't be used to update existing organization data.

To create new organizations with the data importer

1. In Admin Center, click Objects and rules in the sidebar, then select Tools > Data importer.
2. Click Import.
3. Under Target destination, select Organizations.
4. 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.

5. Click Next.
6. 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 and then reupload the file.
7. 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.

Using a CSV import to update existing organization data

The Data import page can only be used to create new organizations via a CSV import during the beta. If you need to use a CSV import to update existing organizations, you must use the Admin Center > People > Bulk actions > Import organizations page. You can also use this page to create new organizations. You'll receive an email when the import is complete.

To update organizations with a CSV import

1. In Admin Center, click People in the sidebar, then select Bulk actions > Import organizations.
2. Choose the type of import you want to perform:

   • Create new organizations

   • Update existing organizations: Use this type of import to replace existing data for the organizations listed in your CSV file.

     Organizations' external_id or name must be included in the CSV so that they can be identified. Other than an organization identifier field, you only need to include the fields that you want to update in the file. If an organization's row has a blank field, it will overwrite the existing data for that organization.

3. Either click Choose File or the Let me paste in data instead link.
4. Click Import.

   After the import starts, the imported changes can't be reverted.

5. (Optional) View the status of in-progress imports on the Admin Center > Objects and rules > Tools > Data importer page. After an import completes, it's captured in the Import history log there.