Rather than add organizations one at a time, you can bulk add several organizations at once 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 also add or update multiple users and multiple custom object records at once.
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.
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.
- The maximum number of rows depends on the import method.
- When using the Bulk actions 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 to import new and existing user and 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.
- 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 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.
- 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.
- In your header row, use either domain_names or default, depending on your import method. They can't be used together.
- 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.
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. |
domain_names (data importer only) |
Detailed information about the organization, such as the address. This information is visible to agents only, not to end-users. Use instead of the default header when using the data importer. |
default (not data importer) |
This is for mapping users to an organization. Enter one or more email
domains, separated with spaces (for example, organization1.com organization2.com).
Use instead of the domain_names header when not using the data
importer. See Automatically adding users to organizations based on their email domain. |
shared (not data importer) |
True or False. Sets the organization as a shared organization. |
shared_comments (not data importer) |
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. |
group | Enter a default group for the organization. See Mapping a group to an organization. |
tags | (Not data importer) 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 organizations, 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. |
(Data importer only) When user and organization tagging has been enabled for
Zendesk Support, you can set tags for the organization. Separate each tag with a
pipe character ( | ). When you bulk import organizations, 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. |
|
organization_fields.<field key> (data importer only) |
When you perform a bulk organization import, you can import a custom
organization field by specifying the organization_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. organization_fields.subscription_date To locate the key for a custom org field, click the Admin icon
( If a field value is not formatted correctly, the import will fail, and you will see details about the error in the import history log. 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 field, use the tag you added when you created the drop-down list.
Note: Lookup relationship fields aren't supported when importing
organizations on the data importer
page.
|
custom_fields.<field key> (not data importer) |
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
( If a field value is not formatted correctly, the import will fail, and you will be emailed 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; 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.
Lookup relationship fields aren't supported when importing organizations on the data importer page. |
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 import organization data
You can use the data importer to import a CSV file that creates new organizations or updates existing organizations, and captures logs of all attempted imports 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 Organizations.
- Under Import type, choose one of the following:
- Create only: Only new organizations are created. Any data in the CSV file pertaining to existing organizations is ignored.
- Update only: Replace data for the existing organizations listed in your CSV file. The external_id is required to update organizations. Any data pertaining to new organizations is ignored.
- Create and update: Create new organizations and update data for the existing organizations listed in your CSV file.
- 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 and 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.
Using a bulk actions import to import organization data
We recommend using the data importer, but you can still use the Bulk actions pages to import new and updated organization data. You'll receive an email when your imports from this page are complete.
- In Admin Center, click
People in the sidebar, then select Bulk actions > Import organizations.
- 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.
-
- Either click Choose File or the Let me paste in data instead link.
- Click Import.
After the import starts, the imported changes can't be reverted.
- (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.
55 comments
Dane
Multi-select custom field for organization is not yet available.
0
Sean Nelson
Thanks Dane, are there plans to support that in the future?
0
mfg
Are organization (or end user) external IDs visible in Support, or are they displayed on the record with other fields?
0
Joyce
The user's external ID can be found on the user profile page, in the bottom left corner, with the last login metadata.
And for Organization, it is also at the bottom left corner, with the last created metadata.
Hope this helps!
0
Hawk Swearingen
For those that are wondering if you can bulk update Checkbox org fields, it's just a True/False value. You'll use the same header style as "organization_fields.<field key>"
True = Checked
False = Unchecked
@Zendesk, this should likely be mentioned in the documentation somewhere
1
Jacquelyn Brewer
1
mfg
is there a way to bulk update users and create organizations on tickets without reopening them?
0
Natalia Tomchyshyn
Hey, mfg!
As an alternative to the Zendesk import tool, consider Help Desk Migration. It imports tickets and all related data into Zendesk automatedly. And KB information as well.
In your CSV file, you can include required and custom fields. As for the custom fields - they can be date, dropdown, number, decimal, and text area.
You can download a sample file and insert your data for importing your records to Zendesk or use the sample file to check how the migration service works. The free demos are available.
For more details on how to set up a file, visit: https://help-desk-migration.com/help/prepare-files-automatic-data-migration-csv/
0
mfg
How does this index edits for similar orgs?
I need to update my organizations, but generally I find my records align best via domain name rather than company name (ie. Joe's Gas, Joe's Gas LLC, Joe's Gas FKA Joseph's Petro). If there are two company names with the same domain, and domains need to be distinct across organizations, how will the orgs be updated? Will it be based / indexed on the name, where the first of the two has the change undone by the second?
0
Tony
according to this article, "If you add a domain that is already mapped to another org, users are mapped to the first organization alphabetically".
I hope that helps,
0
Bellavance,François
I have a question. Lately we passed on Azure Active Directory. Our organisations were auto-updated with a script that do not work anymore. We now have a section named notes where our building code is updated. Azure didn't gave use the hability to update another field. Our buildings are many different schools.
With using bulk updating, can I use this notes field to update the organisation? What can I do for this?
0
Mike DR
That's correct, as long as the format is followed, you'll be able to use the notes field.
1
Mark Molloy
Hello,.
I understand that after a bulk import I have to wait a few hours to see the results in Explore. It's been 48 hours and I still do not see my bulk changes reflected in Zendesk. When I use the data importer, I am told that "Mapping required. One or more fields couldn't be mapped. Modify your CSV file and reupload".
I have tried both bulk import and the data importer. Here are the .CSV headers:
Bulk Import:
Data Importer
Tell me where I am wrong and I will fix it.
0
mfg
Mark Molloy
Your CSV headers look like they might be, but I'm unsure whether those CSV headers are the actual keys (vs titles).
Assuming they are, you can try using the numeric custom field ID (I've found across other features that sometimes this is the most reliable):
Also, I'm curious if this is similar to the Custom Object bulk feature, where I needed to add a fake first column (used "null" for the header).
0
Mark Molloy
mfg These are the actual keys. The 'patch' field is numeric so I tried to bulk import it by itself (with name in the first column, of course) and it worked. I tried one of the other fields (text) by itself and it failed to update. I'll keep trying.
0
Mark Molloy
Well, I'm still stumped. A custom text field will not bulk import (it has in the past). I reduced the .CSV file to one record. The email response says the organization was updated. Nope. Nothing. Nada. Zero. Zilch. Cleared cookies, refreshed the page. Same result. I'm getting heat from management and I don't like it. Help!
0
Emily Ruth
Does ZenDesk add an external id for the orgs you upload or is this a field that you have to add a vaue for?
0
Destiny
Thank you for reaching out.
When uploading organization data to Zendesk, the external_id field is an optional attribute that you can use to associate organizations in Zendesk with an identifier from an external system, such as a CRM. I am afraid we don't automatically generate an external_id for organizations; this is something you would need to provide if you wish to maintain a reference to an ID from an external system. This can be particularly useful for integrations or for tracking purposes across different platforms. If you do not provide an external_id, the organizations in Zendesk will still be created with their own unique organization ID.
I hope that helps.
0
Dan Hammari
Zendesk exports organizations as a text file with each record in JSON syntax. You can use a terminal command called jq to convert the JSON syntax to CSV. Here are the steps I use to format the text file and convert the records.
0
Bellavance,François
Thanks for the reply Mike DR. Just to be sure, if the user has 001 in it's notes, if I want to import an organisation that will auto link to the notes number, is this the correct method?
0
Kirsty Hudd
Hi, I am trying to update existing organization. Custom field . I believe I got the bulk importer to work, I tested with two rows because I want to clear a field, its set with incorrect dropdown value and needs to be cleared. I tried leaving the field blank and typing NULL. the import completed, said successful but nothing updated. I am assuming it is NULL i need to enter as I am also assuming I only need to enter the value in the column that I want to change, if I leave group blank for example because I dont want to change that one then it won't change, please advise?
0
Mark Molloy
Hey Kirsty, I too, encountered something similar: the importer said it worked, but nothing changed. My issue was that my import file's field was not formatted correctly. Verify that the column heading is “Custom_fields.customfieldname”.
As a last resort you might consider deleting the incorrect dropdown value in the organization and then importing the correct ones with the bulk importer.
0
Jupete Manitas
0
Bellavance,François
Hi Jupete. No actually, I'm trying to sync organizations to user field notes. Our users contains the building number in their notes. I want this to auto sync with the same organization with the same number in their Notes too. We have over 60 buildings. Our sync stopped working when we needed to go on Azure AD and the only user field we can write something are the notes and details fields. I thought it would be possible to auto add organization to a user who have 001 inside it's notes section per example.
0
Bellavance,François
https://support.zendesk.com/hc/en-us/articles/4408885980186/comments/7382582654234
Hi Jupete,
What I meant here was link user Notes field to organisation. Per example, I want users who has 418 number in notes to be linked automatically with an organisation.
0