Kaizen #13 - Bulk Write API
Hello everyone!
Welcome to yet another post in the Kaizen series.
This week, we are going to discuss the Bulk Write API.
What is the Bulk Write API?
The bulk write API allows you to insert, update, and upsert records in a module in Zoho CRM in bulk. The primary difference between the bulk write API, and the Insert, Update, Upsert records API, is the number of records that you can handle.
While you can insert, update, and upsert, only 100 records via the Insert, Update, and Upsert Records API per call, you can handle 25000 records via a Bulk Write API call.
When you should use the Bulk Write API?
- When you want to insert, update, or upsert more than 100 records per API call.
- When you want to perform background processes like migration and initial data sync between Zoho CRM and external services.
Below are the differences between Insert, Update, Upsert Records API and the Bulk Write API.
Insert, Update, Upsert Records | Bulk Write API |
You can insert, update, or upsert only 100 records per API call. | You can insert, update, or upsert 25000 records per API call. |
The response is available instantly. | The response is not available instantly; the bulk write job is scheduled, and the status is available after job completion in the callback URL. |
You will receive a success response. | A downloadable ZIP file containing a CSV file, is available with ID, status, and errors if any. |
How does the Bulk Write API work?
To insert, update, or upsert records in bulk, follow the below steps:
- Prepare your CSV file
- Upload your file
- Create a bulk write job
- Check the job status
- Download the result
Now, let us see each step in detail.
1. Prepare your CSV file
The Bulk Write API only accepts a CSV file compressed into a ZIP file as input. The first row should contain the field API names. Refer to the field metadata API, to get the field API names. Each subsequent row contains the data to be written in Zoho CRM. You can insert, update, or upsert records only in a single module through one bulk write API call. Refer to attachments to get a sample ZIP file to bulk-insert contacts.
Input format for each data type
Datatype | Description |
Single Line | Accepts up to 255 characters. Accepts alphanumeric and special characters. Ex: Mike O'Leary |
Multi-Line | Small - accepts up to 2000 characters. Large - accepts up to 32000 characters. Ex: This is a sample description. |
Email | Accepts valid email IDs. |
Phone | Accepts up to 30 characters. This limit may vary based on the value configured in 'Number of characters allowed' in the properties pop-up of the field, in UI. Accepts only numeric characters and '+' (to add extensions). Ex: 9800000099 |
Picklist | You can pass an existing pick list value. If you give a new one, it is automatically added to the pick list set. The pick list value accepts all alphanumeric and special characters. Ex: auto mobile |
Multiselect Picklist | You can either pass the existing pick list values or add a new one. The values are separated by semicolon(;). The pick list value accepts all alphanumeric and special characters. Ex: Analytics;Bigdata |
Date | Accepts date in yyyy-MM-dd format. Ex: 2019-08-28 |
| Date/Time | Accepts date and time in yyyy-MM-ddTHH:mm:ss±HH:mm ISO 8601 format. |
Number | Accepts numbers up to 9 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. Accepts only numeric values. Ex: 350 |
Currency | Before the decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. After the decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal paces' in the properties pop-up of the field, in UI. |
Decimal | Before the decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. After the decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal places' in the properties pop-up of the field, in UI. Accepts only numeric values. Ex: 250000.50 |
Percent | Accepts numbers up to 5 digits. Accepts only numeric values. Ex: 25 |
Long Integer | Accepts numbers up to 18 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. Accepts only numeric values. Ex: 0012345600012 |
Checkbox | Accepts Boolean values (true,false). Ex: true |
URL | Accepts valid URLs. |
Lookup | Accepts the unique ID of the record, which you can get through the get records API. Use the dot(.) operator to link the record. For instance, if there is an account lookup in the Contacts module, you can give the column name as Account.id Ex: Account.id : 4150868000001136302 |
Note:
Multiselect and User datatype fields are not supported in Bulk Write.
Here is a sample content for a CSV file with different field types.
Note:
- To give multiple values for a multi-select pick list field, enclose them in double quotes("") and separate each value with the semicolon(;).
- If your multi-line field has more than one line, input them directly by enclosing them in double quotes("").
2. Upload your CSV file
This involves making a POST API call, with the ZIP file containing the required data. The file is passed as form-data input, with key as file. When the call is successful, you will receive a file_id which you can further use to create a bulk write job.
Headers
Header Name | Description |
feature | bulk-write |
X-CRM-ORG |
3. Create a bulk write job
In this step, make a POST API call with the file_id obtained from the previous step, the callback URL, operation type (insert, update, upsert), module, and field API names. When the call is successful, you will receive a job ID in the response. You can use this ID in another request to poll for the status of the job.
Request URL
{{api-domain}}/crm/bulk/v2/write
Sample Input for bulk insert
{ "operation": "insert", "callback": { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }, "resource": [ { "type": "data", "module": "Contacts", "file_id": "4150868000001038001", "field_mappings": [ { "api_name": "Last_Name", "index": 0, "default_value": { "value": "DefaultValue" } }, { "api_name": "Email", "index": 1 }, { "api_name": "Phone", "index": 2 } ] } ] } |
Sample Input for Bulk Update
{ "operation": "update", "callBack": { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }, "resource": [ { "type": "data", "module": "Contacts", "file_id": "4150868000001123001", "field_mappings": [ { "api_name": "Last_Name", "index": 0 }, { "api_name": "Email", "index": 1 }, { "api_name": "Phone", "index": 2, "ignore_empty": true } ], "find_by": "Email" } ] } |
Input Keys
Key | Description |
operation string, mandatory | The operation to be done. The possible values are—insert, update, upsert. insert - To insert records in bulk. update - To update existing records in bulk. upsert - To update if the record exists or insert the record. |
callback JSON object, mandatory | The callback details. Contains callback URL in the "callback" key and the "method" as post. |
resource JSON array, mandatory | The details of the data in the ZIP file that is uploaded.
|
field_mappings JSON array, mandatory | The details about the fields given in the CSV file. Each object corresponds to each field in the CSV file. Mention the position of the fields in the CSV file in the "index" key, that must start from 0. "default_value" key can be used when a few fields are left blank, and you want the system to fill the default details. |
ignore_empty boolean, optional | If you have a few empty fields while updating the record and you want the system to ignore it, input the value as true. |
find_by string, mandatory (for Update and Upsert) | The system finds the record to be updated by the "find_by" field. It must be a unique field configured in Zoho CRM. To check the same, go to Setup > Modules and Fields > Choose Module > Choose Layout > Choose the field > Click on more options > Check if Do not allow duplicate values is enabled. |
4. Check job status
The Bulk Write API supports polling and callback.
Polling
You can poll to check the status of the scheduled bulk write job with the job ID you received in the previous step.
Request URL: {{api-domain}}/crm/bulk/v2/write/{job_id}
Request Method: GET
Sample Response
- The status can be either ADDED, INPROGRESS, or COMPLETED. Only the COMPLETED jobs will have the "download-URL" key in the response.
- The "file" JSON object in the response represents the total count of records (added, skipped, updated). If the status is mentioned as "skipped" for any record, the reason will be displayed under the ERRORS column, in the downloaded ZIP file.
{ "status": "COMPLETED", "character_encoding": "UTF-8", "resource": [ { "status": "COMPLETED", "type": "data", "module": "Contacts", "field_mappings": [ { "api_name": "Email", "index": 1, "format": null, "find_by": null, "module": null, "default_value": null }, { "api_name": "Last_Name", "index": 0, "format": null, "find_by": null, "module": null, "default_value": { "name": null, "module": null, "value": "DefaultValue" } }, { "api_name": "Phone", "index": 2, "format": null, "find_by": null, "module": null, "default_value": null } ], "file": { "status": "COMPLETED", "name": "Contacts.csv", "added_count": 7, "skipped_count": 0, "updated_count": 0, "total_count": 7 } } ], "id": "4150868000001060014", "callback": { "method": "post" }, "result": { "download_url": "https://download-accl.zoho.com/v2/crm/694902309/bulk-write/4150868000001060014/4150868000001060014.zip" }, "created_by": { "id": "4150868000000225013", "name": "Patricia Boyle" }, "operation": "insert", "created_time": "2020-01-03T15:19:52+05:30" } |
Callback
If you do not want to poll for the status of the job, you can wait for the system to notify you of job completion on the callback URL provided in the POST request.
- The state indicates the successful completion ("state":"COMPLETED") or failure ("state":"FAILED") of the job.
- The callback response will also contain the download URL if the job was completed successfully.
5. Download the result
In this step you can get the result of the bulk write job in a ZIP containing the CSV file. Call the 'download_url' to download the result. The CSV file will contain the first three mapped columns from the uploaded file, and three more columns—STATUS, RECORD_ID, and ERRORS.
Request URL: {{api-domain}}/crm/bulk/v2/write/{job_id}/result
Sample Response
You can see that out of four records, one was skipped because the unique field had a duplicate value.
Limitations
- You can upload only one ZIP file per bulk write API call.
- You can bulk write to only one module per API call.
- The size of the ZIP file being uploaded must not exceed 25 MB. If the file size exceeds the size limit, you must split the file and schedule it as multiple bulk write jobs. Also, you can bulk write only up to 25000 records with 200 column headers per bulk write API call.
- Every successfully scheduled bulk write job reduces 500 credits from your daily credit limit.
- All the mandatory fields must be given in the CSV file if you are trying to insert records. Similarly, ID is mandatory when you are trying to update records.
- Subforms are not supported in Bulk Write.
- Consider that you have a lookup field in the Leads module, that looks up to other leads. You cannot have the value of this field as another Lead that is being written in this bulk write job. In other words, you can only lookup to an existing lead.
For limitations, refer to limitations in our API guide.We hope you found this post useful. If you have any further queries, reach out to us at support@zohocrm.com or let us know in the comments section.
Cheers!
Topic Participants
Sneha Sridharan
richie
Praveen Sankar
Andres
Access
Sticky Posts
Kaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 Nearing 200th Kaizen Post – We want to hear from you! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Recent Topics
Function #9: Copy attachments of Sales Order to Purchase Order on conversion
This week, we have written a custom function that automatically copies the attachments uploaded for a sales order to the corresponding purchase order after you convert it. Here's how to configure it in your Zoho Books organization. Custom Function: HitFree webinar: Security that works: Building resilience for the AI-powered workforce
Hello there, Did you know that more than 51% of organizations worldwide have experienced one or more security breaches, each costing over $1 million in losses or incident response? In today’s threat landscape, simply playing defense is no longer enough."Subject" or "Narration"in Customer Statement
Dear Sir, While creating invoice, we are giving in "Subject" the purpose of invoice. For Example - "GST for the month of Aug 23", IT return FY 22-23", "Consultancy", Internal Audit for May 23". But this subject is not coming in Customer Statement. OnlyApply Vendor Credit Automatically
Hello!!! Is there a way where in we can apply vendor credits automatically on the FIRST OUTSTANDING BILL of the vendor?? We have lots of VENDOR CREDITS ISSUES mostly!!! Applying it manually is a pain for us. Would be great if we have a way to apply theZoho Notebook Sync problem
I'm facing a problem with syncing of notebook on android app. It's not syncing. Sometimes it syncs after a day or two. I created some notes on web notebook but it's not syncing on mobile app. Please help!!!!Apply Vendor Credits Automatically
We are bulk importing Vendor credits in Zoho Books!!! Is there a way to apply vendor credits automatically to the first UNPAID bill of the Vendor?Cant Save Gauge on Creator Page
How to Save Gauge on Creator Page see movie https://vimeo.com/1116410860?share=copy#t=0Apply Advance option not shown in report
We are facing an issue in Zoho Expenses. While approving an Expense Report, the "Apply Advance" option is not appearing under the three dots (More Options). Details: Module: Expense Reports Issue: "Apply Advance" option not visible Status of Report: AwaitingAuto Capitalize First Letter of Words
Hi I am completely new to ZOHO and am trying to build a database. How can i make it when a address is entered into a form field like this: main st it automatically changes is to show: Main St Thank YouFollow-up emails via Workflow Automation not staying in the same thread
Dear Zoho Support Team, I am currently using Workflow Automation in Zoho Campaigns to send follow-up emails. In my test case, I noticed the following behavior: All emails in the automation have the same subject line. If the follow-up email is sent withinClient Script refuses to set an initial value in Subform field
I tried a very simple, 1 line client script to set a default value in a custom subform field when the "Add Row" button is clicked and the user is entering data. It does not work - can someone tell me why? ZDK documentation suggests this should be doable.Emails Are Not Being Delivered to My Inbox
Hello Zoho Support Team, I am experiencing an issue with my Zoho Mail account. The most important problem is that emails are not being delivered to my inbox. Details: My Zoho Mail address: info@coreforcelife.com What happens: I am not receiving any incomingHelp Center IFrame Issue
I have had a working Help Center on my website using an iframe for a while. But now for some reason the sign in page gets a refused to connect error. Can someone please help. If I go to the url manually it works correcltyComment Templates
Is it possible to add a template option for comments? We have some agents in the process who's responses require a pre-formatted layout. It would be incredibly handy to have a template for them where they can insert the template and then add their responses[ZohoDesk] Improve Status View with a new editeble kanban view
A kanban view with more information about the ticket and the contact who created the ticket would be valueble. I would like to edit the fields with the ones i like to see at one glance. Like in CRM where you can edit the canvas view, i would like to editAdding Markdown text using Zoho Desk API into the Knowledge Base
Hi Zoho Community members, We currently maintain the documentation of out company in its website. This documentation is written in markdown text format and we would like to add it in Zoho Knowledge Base. Do you know if there is REST API functionalityAn Exclusive Session for Zoho Desk Users: AI in Zoho Desk
A Zoho Community Learning Initiative Hello everyone! This is an announcement for Zoho Desk users and anyone exploring Zoho Desk. With every nook and corner buzzing, "AI's here, AI's there," it's the right time for us to take a closer look at how the AIShared values: From classroom lessons to teaching moments in customer service
While the world observes Teachers’ Day on October 5, in India, we celebrate a month earlier, on September 5, to mark the birth anniversary of Dr. Sarvepalli Radhakrishnan, a great teacher, renowned scholar, educationist, and advocate for empowerment.Create a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM
How to create a list of customers who participated in specific Zoho Backstage events and send them an email via Zoho CRM? I was able to do a view in CRM based on customer that registered to an event, but I don't seems to be able to include the filterZoho Desk blank page
1. Click Access zoho desk on https://www.zoho.com/desk/ 2. It redirects to https://desk.zoho.com/agent?action=CreatePortal and the page is blank. Edge browser Version 131.0.2903.112 (Official build) (arm64) on MacOSI hate the new user UI with the bar on the left
How can I reverse this?Question regarding import of previous deals...
Good afternoon, I'm working on importing some older deal records from an external sheet into the CRM; however, when I manually click "Add New Deal" and enter the pertinent information, the deal isn't appearing when I look at the "Deals" bar on the account'sClient Script also planned for Zoho Desk?
Hello there, I modified something in Zoho CRM the other day and was amazed at the possibilities offered by the "Client Script" feature in conjunction with the ZDK. You can lock any fields on the screen, edit them, you can react to various events (fieldOne person/cell phone to manage multiple accounts
Hi. I have a personal Free account to keep my own domain/emails. Now I need to create a Business account to my company's own domain, but I have only one mobile phone number I use to everything. How do I do to manage this? Can I manage a Free domain andTracking KPIs, Goals etc in People
How are Zoho People users tracking employee targets in People? For example, my marketing assistant has a target of "Collect 10 new customer testimonials every month". I want to record attainment for this target on a monthly basis, then add it to theirZoho Desk: Ticket Owner Agents vs Teams
Hi Zoho, We would like to explore the possibility of hiding the ‘Agents’ section within the Ticket Owner dropdown, so that we can fully utilise the ‘Teams’ dropdown when assigning tickets. This request comes from the fact that only certain agents andCan not Use Attachment Button on Android Widget
this always pops up when I touch the attach button on android widget. going to settings, there is no storage permission to be enabled. if I open the app, and access the attach feature there, I can access my storage and upload normally.Announcing new features in Trident for Mac (1.24.0)
Hello everyone! Trident for macOS (v.1.24.0) is here with interesting features and thoughtful enhancements to redefine the way you plan and manage your calendar events. Here's a quick look at what's new. Create calendar events from emails. In additionVendor Master Enhancements for Faster Purchase Entry
I’d like to suggest a few features that will improve accuracy and speed during purchase voucher entry: Automated Item Tax Preference in Vendor Master Add an option to define item tax preference in the vendor master. Once set, this preference should automaticallyMass Mail Statistics - Number of unsent emails
How do I find out which emails were not sent?Est-il possible d'annuler l'envoi d'un mail automatique ?
Bonjour, Lorsque je refuse un candidat, il reçois un mail dans les 24h pour l'informer que sa candidature n'est pas retenue. J'ai rejeté un candidat par erreur. Savez-vous s'il possible d'annuler l'envoi de ce mail ? Merci d'avance pour votre aide.embed a form in an email
Hello, how to embed a form in an email that populates Zoho CRM cases? I would like to send emails to a selected audience offering something. In the same email the recipients - if interested - instead of replying to can fill in a Zoho CRM form that createsZoho Bookings - Reserve with Google
Does Zoho Bookings plan to to integrate with Reserve with Google?How to add Zoho demo site page designs to my Zoho Sites website
Hi, I would like to add the design from the following demo URLs into my current Zoho website. I have already created two new pages on my site, named “Menu2” and “Menu3.” For the “Menu2” page, I want to use the design from this demo: https://naturestjuice-demo.zohosites.com/menuDigest Août - Un résumé de ce qui s'est passé le mois dernier sur Community
Bonjour chère communauté ! Voici le résumé tant attendu de tout ce qui a marqué Zoho le mois dernier : contenus utiles, échanges inspirants et moments forts. 🎉 Découvrez Zoho Backstage 3.0 : une version repensée pour offrir encore plus de flexibilité,Global Sets for Multi-Select pick lists
When is this feature coming to Zoho CRM? It would be very useful now we have got used to having it for the normal pick lists.Text snippet
There is a nice feature in Zoho Desk called Text Snippet. It allows you to insert a bit of text anywhere in a reply that you are typing. That would be nice to have that option in Zoho CRM as well when we compose an email. Moderation Update: We agree thatKaizen #206 - Answering your Questions | Displaying Related Purchase Orders from Zoho Books in CRM Deals using Queries
Hello everyone! We're back with another post in the Kaizen series. We're grateful for the feedback we received from all of you! One of the questions we received was "I would like to see the list of Purchase Orders in Zoho Books for a Deal in CRM." WeAdd Analytics function for Title case (capitalising each word in a string)
At present, you can only capitalise each word in a string in Analytics during data import. It would be really useful to be able to do this with a formula column, but there is no Title Case function.How to conditionally embed an own internal widget with parameters in an html snippet?
Hello everyone, I'm trying to create a dynamic view in a page using an HTML snippet. The goal is to display different content based on a URL parameter (input.step). I have successfully managed to conditionally display different forms using the followingNext Page