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!
Access your files securely from anywhere
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
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
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho CRM Resources
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Cross Data Center Support for 1:1 Chats with External Users
Hello Zoho Cliq Team, We hope you're doing well. We appreciate the recent enhancement that enables cross data center collaboration in external channels, which has already improved communication across distributed teams. However, we’ve noticed that thisSupport Bots and Automations in External Channels
Hello Zoho Cliq Team, How are you? We actively use Zoho Cliq for collaboration, including with our external developers. For this purpose, external channels are a key tool since they work seamlessly within the same interface as all of our other channelsAnswer Bot and Personalized Questions
Hi there, I have the same problem using the SalesIQ Answer Bot and the Zoho Desk Answer Bot (which really need different names, to be honest, in order to avoid confusion...) Customers that visit our website ask questions in the form of "What do you do?"Handling Greetings/Small Talk at the Beginning of a Zobot Conversation
Hello everyone, I’m currently configuring a **Zobot** in Zoho SalesIQ and everything is working as expected, except for one specific scenario at the very beginning of the conversation. My target audience has the habit of starting with a **greeting orRegex in Zoho Mail custom filters is not supported - but it works!
I recently asked Zoho for help using regex in Zoho Mail custom filters and was told it was NOT supported. This was surprising (and frustrating) as regex in Zoho Mail certainly works, although it does have some quirks* To encourage others, here are 3 regexImporting a new list into campaigns
I'm in the middle of switching my email platform to campaigns. I have a list that I want to import, and it overlaps with my existing Zoho CRM list. The fields in my Zoho CTM are more robust. Will this new list that I upload into my campaigns overwriteClient Script Payload Size Bug
var createParams = { "data": [{ "Name": "PS for PR 4050082000024714556", "Price_Request": { "id": "4050082000024714556" }, "Account": { "id": "4050082000021345001" }, "Deal": { "id": "4050082000023972001" }, "Owner": { "id": "4050082000007223004" }, "Approval_Status":Webform & spam
Hi, We set up 2 webform on our website, fowarding the content to Zoho CRM. Since it has been opened up, we are getting lot of spam message (for now about 20 a day). To lower the amount of false new leads we added the captcha field and new enquieries are send to the Approval Leads list. However we still get some spam. Is there any "anti spam" mechanism built in Zoho CRM, or how is the best way to avoid these kind of spam ? Thankswhen I email a invoice how can i see it was sent and also were i can go to see all emails sent
when I email a invoice how can i see it was sent and also were i can go to see all emails sent?Kaizen #208 - Answering your Questions | Functions, AI and Extensions
Hello Developers! Welcome back to a fresh week of Kaizen! We are grateful for your active participation in sharing feedback and queries for our 200th milestone. This week, we will answer the queries related to Functions and Extensions in Zoho CRM. 1.Export Invoices to XML file
Namaste! ZOHO suite of Apps is awesome and we as Partner, would like to use and implement the app´s from the Financial suite like ZOHO Invoice, but, in Portugal, we can only use certified Invoice Software and for this reason, we need to develop/customize on top of ZOHO Invoice to create an XML file with specific information and after this, go to the government and certified the software. As soon as we have for example, ZOHO CRM integrated with ZOHO Invoice up and running, our business opportunitiesShowing description in timesheet and timelogs.
I am wondering if it’s possible in version 5 of Zoho People to have the description show by default or with a manipulation on the user’s part. Let me show you what I mean. As you can see this is the view for the users. Now if they want to see the fullHow can I see content of system generated mails from zBooks?
System generated mails for offers or invices appear in the mail tab of the designated customer. How can I view the content? It also doesn't appear in zMail sent folder.New in Cadences: WhatsApp follow-ups, upgraded limits, and options for add-ons
Hello everyone, We're rolling out two key updates to help you engage better and scale smarter with Cadences in Zoho CRM. Reach customers on WhatsApp, directly from Cadences Previously, Cadences have enabled you to automate follow-ups through emails, calls,CRM Blueprint Notification by Cliq
Dear Zoho team, In Workflow, there is nofication by cliq, but in blueprint, there is no option as cliq notification. I think it is very convenient to get notified by Cliq , as there are multi modules in apps, but we will always check CliqsZoho People Attendance Regularization – Wrong Total Hours Displayed
While using Zoho People, I observed that the attendance regularization is showing wrong total hours when applied to past dates. For example, if a check-in is added at 10:00 AM and check-out at 6:00 PM for a previous date, the system sometimes calculatesSync Contacts in iOS
What does the "Sync Contacts" feature in the iOS Zoho Mail app do?Live webinar: Craft the ideal sales pitch deck with Show
Every great sale starts with a great story. And your pitch deck? That’s where the story takes shape. But too often, these presentations end up looking generic, overloaded with text, or lacking structure. The good news is, it's easier to fix than you think!Project Statuses
Hi All, We have projects that sometimes may not make it through to completion. As such, they were being marked as "Cancelled". I noticed that these projects still show as "Active" though which seems counter intuitive. In fact, the only way I can get them👋 Welcome to the Zoho MCP Community
Hello all, glad to have you here! This is your space for everything AI agents, MCP tools, and intelligent business apps. This community is for you — developers, partners, creators, and businesses exploring how agents can transform work. Whether you’reSuitability of Zoho One (Single User License) for Multi-State GST Compliance & Cost Analysis
Hello Zoho Team, I am an e-commerce business owner selling on platforms like Amazon, Flipkart, and Meesho, and I'm currently using their fulfillment warehouses. I have two GSTIN registrations and am planning to register for an additional 2-3 to expandDNS Manager
Where Can I find my DNS manager so I can link this to click funnels or AWEBERForwarder
Hi, I tried to add a forwarder from which emails are sent to my main zoho account email . However, it asks me for a code that should be received at the forwarder email, which is still not activated to send to my zoho emial account. So how can I get theForwarder
Hi, I tried to add a forwarder from which emails are sent to my main zoho account email . However, it asks me for a code that should be received at the forwarder email, which is still not activated to send to my zoho emial account. So how can I get theHow do I sync multiple Google calendars?
I'm brand new to Zoho and I figured out how to sync my business Google calendar but I would also like to sync my personal Google calendar. How can I do this so that, at the very least, when I have personal engagements like doctor's appointments, I canNeed to extract date from datetime field
I have a datetime field and need only the date part from it. I am unable to find a built-in function that would be <DateTime>.Date(). I don't think I want to go the string conversion route of converting the datetime to string and then parsing out values and create a date out of it. Any one out there has a better solution to this? Thanks in adavnce. Regards Moiz Tankiwala Smart Training & IT SolutionsHow to Hide Article Links in SalesIQ Answer Bot Responses
I have published an article in SalesIQ, and the Answer Bot is fetching the data and responding correctly. However, it is also displaying the article link, which I don’t want. How can I remove the link so that only the message is shown?India Tech Support
Is there no phone tech support number for India? And no chat facility either?additional accounts
If I brought 5 emails to my account. Can I later buy additional emails.Issue in Zoho People Regularization – Incorrect Hour Calculation
I have noticed that when applying attendance regularization in Zoho People for previous dates, the total working hours are not calculated correctly. For example, even if the check-in is 10:00 AM and check-out is 6:00 PM, the system shows an incorrectWhy I am unable to configure Zoho Voice with my Zoho CRM account?
I have installed Zoho Voice in my Zoho CRM, but as per the message there is some config needed in Zoho Voice interface. But when I click on the link given in the above message, I get an access denied page.Issue with Hour Calculation in Zoho People Attendance Module
I have noticed an issue in the attendance regularization feature of Zoho People. When trying to regularize past dates, the total working hours are not calculated correctly. For example, if I enter a check-in and check-out time for a previous day, theCliq Meeting Calls No Audio and Screen Share
When in a Cliq channel meeting, the audio does not work at all on pc. When i use my phone as audio source, screen share on pc does not work. I have updated audio drivers but the strangest thing is that during a 1 on 1 call, it works well. Therefore theBug in Total Hour Calculation in Regularization for past dates
There is a bug in Zoho People Regularization For example today is the date is 10 if I choose a previous Date like 9 and add the Check in and Check out time The total hours aren't calculated properly, in the example the check in time is 10:40 AM checkWork anniversary and birthdays on connect
Hello, I like the idea of having employee's work anniversary and birthdays on the dashbaord. Do you have to have the employee complete this information themselves in connect settings, or does it pull from their directory settings? (ie. we use Zoho oneAlias Email Id already exists
Hi I'm trying to create an alias : contact @ yoavarielevy.co.il but i get the message Alias Email Id already exists I had an account with the same name but I deleted it. Can you help? Thanx YoavBANK FEED - MAYBANK , provider from YODLEE IS NOT WORKING
As per topic, the provider YODLEE is not working for the BANK FEED. It have been reported since 2023 Q3, and second report on 2023 Q4. now almost end of 2024 Q1, and coming to 2024 Q2. Malaysia Bank Maybank is NOT working. can anyone check on this issue?Feature Request: Ability to Set a Custom List View as Default for All Users
Dear Zoho CRM Support Team, We would like to request a new feature in Zoho CRM regarding List Views. Currently, each user has to manually select or favorite a custom list view in order to make it their default. However, as administrators, we would likeAdding Multiple Products (Package) to a Quote
I've searched the forums and found several people asking this question, but never found an answer. Is ti possible to add multiple products to a quote at once, like a package deal? This seems like a very basic function of a CRM that does quotes but I can'tZoho Commerce in multiple languages
When will you be able to offer Zoho Commerce in more languages? We sell in multiple markets and want to be able to offer a local version of our webshop. What does the roadmap look like?Next Page