Rather than adding custom object records one at a time, you can bulk-add and update many records at once by importing a CSV (comma-separated values) file. You must be an administrator to bulk import custom object records.
Requirements and limitations
- 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 32 KB in size.
- The import CSV file can contain a maximum of 102 columns.
- Don't include the same record 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.
- Bulk importing custom object records can't be undone. Before importing the CSV file that contains the information of all your current records, test that same CSV file with a single record to make sure the upload works as intended.
Creating custom object records CSV 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 a name field. Optionally, if you wish to bulk update the records in the future, you must also include an external_id field. All other field names in the header row should be exact matches to the field keys in your custom object.
- To import values for dropdown fields, use the custom dropdown field's field_key as the column heading and specify the options tag, not the user-friendly value.
- To import values for lookup relationship fields, use the custom lookup relationship field's field_key as the column heading and provide either the record's id or external id. If you use the record's ID, provide the value. If you use the External ID, use the format external_id:value, where value is replaced with the related record's external ID value.
- If you are not importing data for a field, do not list it in the header row.
- Add line breaks to notes or multiline custom fields by pressing ALT+ENTER on Windows or CTRL+OPTION+RETURN on macOS.
If you are performing a bulk upload of records to seed your existing data for a new custom object, we recommend that you walk through Planning your custom objects workflow. During the process, we recommend creating spreadsheets with this data for each of your custom objects. If structured carefully to align with the custom object you created in Zendesk and the guidelines above, you can export the spreadsheet as a CSV file and use it for this bulk upload. In this case, make sure to add a column for the external_id and add an ID for each record if you want the option of bulk updating them in the future.
Importing the custom object records CSV file
You can use the data importer to import a CSV file that creates new custom object records or updates existing records and capture logs of all attempted imports through the Data importer page.
- Before you can bulk upload records for a custom object, you must create the custom object in Zendesk.
- In Admin Center, click Objects and rules in the sidebar, then select Tools > Data importer.
- Click Import.
- Under Import type, choose one of the following:
- Create only: Only new custom object records are created. Any data in the CSV file pertaining to existing records is ignored.
- Update only: Replace data for the existing custom object records listed in your CSV file. Any data pertaining to new records is ignored.
- Create and update: Create new custom object records and update data for the existing custom object records listed in your CSV file.
- Under Target destination, select the custom object's name.
- 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 re-upload 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.
14 comments
Bryan Naing
Can we import a look-up relationship field using this method?
0
Tony
I'm not too sure you can import a look-up relationship field at the moment. However, there are some article that might help you like this linked article here, and then this one.
I hope that helps.
0
Caleb Harrill
Hey! Is there a samples "upload csv file" that we could download for reference. Maybe it could be added to this article?
1
Mike DR
Will flag this article for you to request our team to add a sample CSV file for importing custom objects.
0
mfg
I'm not sure how to manage this using a .csv via an end point, but I'd like to be able to automate sending this update without paginating or hitting a server 429 error (too many requests), and without throttling our API calls. the bulk import UI features are super helpful to manage resources, is there some kind of bulk API import method?
1
mfg
When using the Data Importer tool, I've tried to include a 'name' field in the header as "name" and as "custom_object_key.name" and as "name*" (the way it is documented) but the nomenclature / format keeps returning that the file headers aren't mapping. What is the proper format?
0
Paolo
You can use the Create Custom Object API to create your objects. However, if you are planning to upload it via CSV, the data importer tool is the one to use. For now, unfortunately, there is no available endpoint for bulk upload of custom objects. Please refer to this article for more information: Creating custom objects workflow and samples.
As for the error that you are getting with the data importer tool, make sure that the following requirements are met to avoid any issues. This can be seen above.
If you continue to experience issues with that data importer tool, I highly suggest reaching our to our Support Team for further checking.
Best,
Paolo | Technical Support Engineer | Zendesk
0
mfg
UPDATE: MOVING 'NAME' TO THE SECOND COLUMN MAPPED IT. DUNNO 🤷♂️
That's the issue - the CSV importer isn't recognizing that there's a column header with the title 'name'. I'm following the documentation, but a CSV template would be helpful since it seems there's some vagueness. It's recognizing some of the headers though:
Importer results:
0
mfg
It would be great if the importer ran as a patch like the API rather than needing to use update and create separately. In any case, the error log for the update run is unclear.
When you try to update from a create run, the system tells you clearly that the external_ID is already in use. When you try to create from an update run, you get a pretty jumbled error message including non-essential technical info that - I believe - indicates that the external_ID doesn't exist (ie it can't update a record that doesn't exist). It would be helpful to admins if the message was a bit more plain.
0
Chris Fassano
In case other Zendesk admins are running into the same issue I am…
For Data Importer to be able to bulk update organization records, the orgs need to have an external_id already populated. Data Importer does not use the organization ID as the unique identifier.
I created a feature request to allow Data Importer to use the Zendesk organization ID when bulk updating. Please upvote if you think this is a good idea.
https://support.zendesk.com/hc/en-us/community/posts/6980652975642-Data-Importer-Use-Org-ID-as-identifier-instead-of-external-id-when-updating-orgs
0
Carl Joseph
Hi mfg. Yes, the team are considering releasing an API for this, but we don't currently have a timeline for it. I'm curious how you might use such a feature? Are you able to let me know some details of your particular use case or ideas here?
Thanks,
Carl
0
mfg
Carl Joseph - We use Tray for many Zendesk automations that either handle a bunch of requests, or extend existing Zendesk functionality. In terms of Custom Objects, we use one that updates the records based on a report generated by an external resource. This POST/PATCH includes about 5,000 records on a daily basis. For Tray and Zendesk limits, this is pretty resource intensive.
I'm not sure what other file upload API actions are supported by other end points, but I'm seeing a PUT method for User Images. Using the API in this way would allow us to bypass using the UI, and automatically process these on an off-hours schedule.
0
Michal Klimek
Hey Thomas,
To import values for multi-select fields, you should use the custom multi-select field's field_key as the column heading. For the values, you can specify space-delimited multi-select tags or space-delimited multi-select option IDs.
Here's an example using a custom clothing product object where colors are set as a multi-select field:
name,colors,in_stock
Short sleeve t-shirt,cardinal_red black white deep_green,true
Long sleeve t-shirt,gold royal_blue yellow,false
In this example:
Please let me know if you need any further assistance!
Thanks,
Michal | Senior Software Engineer | Zendesk
0
Jihoon Lee (이지훈)
When importing a custom object, it is not imported in the order of the CSV rows. Since I cannot sort the custom object, this list is displayed as is to the end user or agent. If the custom object is a number, it is not sorted, which confuses the users.
1) Is there any way to import a custom object in CSV order?
2) Do you plan to support sorting in custom objects? (Like the ticket field option)
0