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
Ben Van Iten
Hi Aditya,
The first thing I would do is add the groups you want to use, as you will not be able to map users to a group that does not exist already.
Then from there, when you import agents you have the option to map them to this group.
I assume you are referring to agents because only agents can be in "groups" but let me know if I'm off base!
0
Liz W
Hi all! I'm puzzled by something here and wondering if anyone can help me out.
The original article says the external_ID can be a unique identifier. I'm hoping this is true; I'm preparing to import all of our B2B customer organizations into our new help center before importing users, and there are some companies with identical names. We have unique IDs for each that we're planning to upload as well.
However, in the comments, Patrick from Zendesk says that only the company name is a unique ID. On the other hand, the comments from Diogo and Austin in response to related questions from other posters suggest that the external_ID can be the unique identifier (and can even be used to update company names).
Anyone have any insight onto which is correct (or perhaps a nuance of this that I'm overlooking)?
Thanks!
0
Paul K
Full XML exports aren't supported anymore, and CSV export only exports ticket information, so what is the solution to exporting Organization data now? I tried exporting a JSON file then opening in Excel and separating the data by commas, but the formatting is super messy.
The full XML exports were ideal for an organization data export.
2
Dave Dyson
Hi Paul,
Full XML Export isn't available for accounts with more than 200,000 tickets (which I believe yours does have), but User XML Export should still be available, and that does include Users, Groups, and Organizations: Exporting data to a JSON, CSV, or XML file
1
Paul K
@... Perfect, that's exactly what I needed. Thank you!
0
Dave Dyson
Glad I could help, Paul!
0
Stuart Buddrige
Hi,
Is there a way to import information to append it to existing data already in ZenDesk?
For example, if we have an organisation with some data in the Notes field, and in the import file we wish to add some extra Notes in, but keep the original Notes, can this be done?
Thanks,
0
Austin Killey
Really good question @....
It looks like you'd just need to export your org data first so that its Notes field has the current text showing in the data. From there, you could edit the Notes field in that exported data to add on any additional text to the existing text, and then import that updated data back into your Zendesk account.
I had to test on my end just to be sure, but it looks like that may be one of our best bets for appending existing organizational data. Let us know if you have any other questions!
0
Stuart Buddrige
@Austin K Thanks for confirmation.
It's not the best solution really, especially when you can do an import of notes at a user level and if you separate this with a space, it DOES append any data in the import file to the existing data in ZenDesk. Why the difference between the Org level and User level?
Thanks,
0
Vincent van Elsas
In the section about 'Importing the CSV organization data file' you say you need to bulk import these in 'users' page, but there is an 'organization' page where you need to import these.
Besides that, I'm wondering how I could set up the difference between an organization, location and users. e.g. we have customer A, with locations XYZ and users 1 to 10. How do I set this up best? Can I use Groups for this purpose?
0
K
I understand you would like to use Organizations for your customers and then organize the users in those Organizations by location. The following three resources will help you with this workflow and learn about using Organizations to organize end users:
One suggestion you and your team can consider is to use Organization fields to differentiate locations. For example, you could create customer A as an organization and then create an organization field for locations X, Y, Z.
I hope this suggestion works for you and your team! :)
0
Tiffany Brown
Hi, forgive me if I missed this. With the new change, I no longer see the Bulk Org import option, I only have User or delete. Has this completely been removed, or do I need permission for that?
1
Josh
Thank you for reaching out to us. This is not removed actually however, you will need to be an admin to access this.
0
John DiGregorio
I am trying to do a bulk import of organization data. I want to pass the account owner and ARR for each account. If the account doesn't existing in Zendesk I want to skip over it. However, the option for Create new Organizations can't be disabled
Bulk import organizations
Create new organizations
Organizations that exist in the import data, but not in Zendesk, will always be created.
Update existing organizations
Update existing organizations with the attributes specified in the import data.
1
Nelson Garcia Borrego
Hi!
I am trying to make a bulk upload for the organizations, and I see this message:
"Your job has been submitted. You will receive an email with a download link shortly."
however, It's been several days since I did this and I don't receive anything still.
Can someone tell me what I am doing wrong?
0
Frank Roberts
Check your inbox for a success or failure message. If the job failed, the attached csv should have the reason. Perhaps it in the junk mail folder if you don't see it in your inbox.
0
Juan Camilo
Hi,
I need to update the organization name, how can I do it if the organization name is the unique ID?
1
Brett Bowser
Are you updating the organization through the agent interface or uploading a CSV file? If through the agent interface, you should be able to change the name from the organization page and the ID would remain the same. If you're updating the name through a CSV file the same should be applicable. Just change the name field and leave everything else in the row the same.
Let me know if I'm misunderstanding your question!
-1
Mathew St Thomas Jr
Hello!
When trying to bulk update organizations, I am getting several that come back failed stating "Name: {company name} has already been taken". Any reason why this would happen while the other organizations I uploaded updated correctly?
0
Jacob Meesenburg
Is it possible to sync the organisations from the sell modul to the support modul? I have quite a lot of comoanies in the sell account but not many in the zendesk suppot account
0
Dane
The common root cause for this behavior is due to duplicate company name in your CSV or existing orgs. You'll need to manually check it on your end.
Hi Jacob,
Unfortunately, this feature is not supported.
0
Terena Eron
Hello, is there any plan to up the number of rows of data that can be uploaded at a time?
0
Jo Tatti
Is there a plan to restore the export to CSV option? The JSON is unusable.
0
John DiGregorio
I am a little confused - it says the name is required. However the next bullet says you can use an external_id. All of our systems are linked using the SalesForce account id as the names could be different between systems. How can you make the CSV import use the external_id versus the name? Also when I look under the organization fields I don't see external_id
1
John DiGregorio
Liz W did you ever get an answer for this. I have wasted 4 hours today trying to get this to work and can't. It is frustrating that the name is required but then it goes on to say a unique_id can be used. The only thing I have found with testing is if I have two accounts all with the same information on the csv except for the external id it will match the right one. However, you can't have two companies in Zendesk with the same name so what good does it do
1
Sushree Peda
I am experiencing issues while importing from a csv. below is the data
name
1315-ENERGY EXPRESS 66 #1315
below is the error:
We've been notified about this. Please contact our Customer Support team for more information about the error below:
#Parameter 'name': Expected type T.any(Integer, String, T::Boolean), got type NilClass
Caller: /app/.bundle_deployment/ruby/2.7.0/gems/sorbet-runtime-0.5.10690/lib/types/private/methods/call_validation.rb:201
Definition: /app/components/group/public/group_component/repository/group.rb:107
0
Brandon Niblock
Sushree Peda
I reached out to support on this. The solution is to remove the blank columns with no data from the CSV.
0
AJ Sneed
Is there a way to add tags without it removing anything else that is listed on the organization? I've tried using it but it overwrites what's there and has been very frustrating.
0
Dane
When you are bulk importing orgs, the tags in your CSV file will replace the existing org tags. To avoid this from happening, you might as well consider using the update tag API endpoint.
0
Sean Nelson
Are multi select Org fields able to updated via bulk upload? If so, how would I go about formatting the field in the .CSV file to have multiple options entered?
If, for example, I want to have: custom_field.product_lines imported with multiple selections, would I have the cells in the .CSV under that header entered with each selection separated by a comma?: product_a, product_c, product_f
0