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 #222 - Client Script Support for Notes Related List
Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore howKaizen #217 - Actions APIs : Tasks
Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.Kaizen #216 - Actions APIs : Email Notifications
Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes areKaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achievedKaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script
Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.
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
Zoho Books' 2025 Wrapped
Before we turn the page to a new year, it’s time to revisit the updates that made financial management simpler and more intuitive. This annual roundup brings together the most impactful features and enhancements we delivered in 2025, offering a clearCan multiple agents be assigned to one ticket on purpose?
Is it possible to assign one ticket to two or more agents at a time? I would like the option to have multiple people working on one ticket so that the same ticket is viewable for those agents on their list of pending tickets. Is something like this currentlyEdit default "We are here to help you" text in chat SalesIQ widget
Does anyone know how this text can be edited? I can't find it anywhere in settings. Thanks!Can't change form's original name in URL
Hi all, I have been duplicating + editing forms for jobs regarding the same department to maintain formatting + styling. The issue I've not run into is because I've duplicated it from an existing form, the URL doesn't seem to want to update with the newFeature Request: Sync Leave Tracker to Zoho Mail / Calendar or provide option to download information
Zoho Leave Tracker offers the option to sync the leave Calendar to Microsoft 365 and Google Calendar. Adding an option to sync to Zoho-Mail Calendar would avoid duplication and add significant value for users. An alternative would be to allow users toCompensation | Salary Packages - Hourly Wage Needed
The US Bureau of Labor Statistics says 55.7% of all workers in the US are paid by the hour. I don't know how that compares to the rest of the world, but I would think that this alone would justify the need for having an hourly-based salary package option.Multiple currencies - doesn’t seem to work for site visitors / customers
I am trying to understand how the multiple currency feature works from the perspective of the website visitor who is shopping on my Zoho Commerce site. My site’s base currency is US Dollars (USD) but my store is for customers in Costa Rica and I wouldArchiving Contacts
How do I archive a list of contacts, or individual contacts?How do people handle using Outlook and Zoho Project calendar at the same time?
We have an ongoing problem in our organisation where we use Zoho Projects to plan all of our projects tasks and that also allows us to look forward using the workload report to see which of our consultants are overstretched etc and which are available.10GB Email Storage Limits in Zoho CRM
We’ve had Zoho One for almost 5 years and have always synced our emails from Gmail via IMAP… As of late, we’ve run into issues with our emails not syncing, due to being over the 10GB storage cap… What’s very odd is that we haven’t changed a thing? I knowPerformance is degrading
We have used Mail and Cliq for about three years now. I used to use both on the browser. Both have, over the past 6 months, had a severe degradation in performance. I switched to desktop email, which appeared to improve things somewhat, although initialHow to set page defaults in zoho writer?
hi, everytime i open the zoho writer i have to change the default page settings to - A4 from letter, margins to narrow and header and footer to 0. I cannot set this as default as that option is grayed out! so I am unable to click it. I saved the documentUnable to Send Different Email Templates for Different Documents in Zoho Sign
Hello Zoho Community, I am facing a limitation with Zoho Sign regarding email notifications sent to customers when a document is sent for signing. Currently, whenever I send any template/document for signing, the email notification that goes to the customerEnable History Tracking for Picklist Values Not Available
When I create a custom picklist field in Deals, the "Enable History Tracking for Picklist Values" option is not available in the Edit Properties area of the picklist. When I create a picklist in any other Module, that option is available. Is there a specific reason why this isn't available for fields in the Deals Module?ZO25: The refreshed, more unified, and intelligent OS for business
Hello all, Greetings from Zoho One! 2025 has been a remarkable year, packed with new features that will take your Zoho One experience to the next level! From sleek, customizable dashboards to an all-new action panel for instant task management, we’veVault crashes on Android Devices
Vault is continuously closing after entering the master password on my Android device. After several attempts I get a system message that says there is a bug in the app. I've uninstalled and reinstalled the app, and cleared the app cache, but nothing¿Cómo puedo configurar las contraseñas creadas bajo una directiva para que nunca caduquen y no aparezcan como caducadas en los informes?
¿Cómo puedo configurar las contraseñas creadas bajo una directiva para que nunca caduquen y no aparezcan como caducadas en los informes? La razón por la cual contraseña estas no deben caducar es porque su actualización depende de mi cliente y no de mí.Camera access
My picture doesn't appear in a group discussion. (The audio is fine.) The guide says "Click the lock icon on address bar," but I can't find it. Advise, pleaseAre static links available
I'm still using Zoho Meeting in trial mode. My previous webinar software provided a static link, and I made the mistaken assumption that I could send out my link and start a meeting later. Mass confusion, but my fault. With a paid version do you get aWhy is Zoho Meeting quality so poor?
I've just moved from Office 365 to Zoho Workplace and have been generally really positive about the new platform -- nicely integrated, nice GUI, good and easy-to-understand control and customisation, and at a reasonable price. However, what is going onHow to print a label from zoho creator app?
Hello, I would like to print a label from zoho creator app record similar to attached one. Size 74mm x 102mm. I tried record template. It leaves plenty of space around the content and also I couldn't set the height of the page. So it is not printing properly. Could someone please direct me to right direction for this requirement?Integration between "Zoho Sprints Stories" and "Zoho Projects Tasks/Subtasks"
We have two separate teams in our organization using Zoho for project management: The Development team uses Zoho Sprints and follows Agile/Scrum methodology. The Infrastructure team uses Zoho Projects for traditional task-based project management. InWhere can we specify custom CSS in Zoho Forms custom theme ?
I'm using a form with a dark theme. The OTP popup window is unreadable, because for some reason, the OTP popup background fixes color to white, but still takes the font color specified in the custom theme. This ends up as white on white for me, renderingTeam Gamification
Would love to motivate, engage and encourage our team with our social media posts. Would like to include Gamification features of Social Media in Zoho Social or Marketing Automation. And also bring in Social Advocacy tools/tracking/management to these,Sync Data from MA to CRM
Currently, it's a one-way sync of data from the CRM to MA. I believe we should have the ability to select fields to sync from MA to the CRM. The lead score is a perfect example of this. In an ideal world we would be able to impact the lead score of aUpdate CRM record action
Currently, MA only offers a "Push Data" action to push data to a CRM module. This action is built to cover the need to both create a new record and update an existing record. Because it has been implemented this way all required fields on the CRM modulePro Lite Upgrade - Quick Access Tray
Hello, I was going to upgrade to Pro Lite but the Quick Access Tray feature isn't available for Windows. Of the four features not available for Windows, the QAT is what I'm most interested in. Are there plans to add this feature for Windows anytime soon?Boost your CRM communication with new font types, sizes, and default reply-to options while composing emails
Hello Everyone, We’re excited to introduce a series of impactful enhancements to the email composer settings in Zoho CRM. These updates enable you to personalize and optimize your customer interactions with greater efficiency. So what's new? Add customFeature Enhancement Request – Text Formatting Options in Item Description (Zoho Books/Quotes Module)
Dear Zoho Development Team, Greetings from Radiant360 Integrated Technical Services LLC. We would like to bring to your attention a functional limitation we've encountered within the Item Table / Quote Description section of Zoho Books (and Zoho CRM Quotes).3 year sick leave cycle
How do you set up a sick leave cycle for South Africa? In SA the sick works like this for the first 6 months you get 0.83 paid sick days a month, then after 6 months you sick leave balance is reset to 30 days that can be used over a 36 month cycle. ThisWorkDrive and CRM not in sync
1/ There is a CRM file upload field with WorkDrive file set as the source: 2/ Then the file is renamed in WorkDrive (outside CRM): 3/ The File in CRM is not synced after the change in WorkDrive; the file name (reference) in CRM record is not updated (hereIs Zoho Communityspaces now part of Zoho One?
Is Zoho Communityspaces now part of Zoho One?Bigin’s 2025 Evolution: Highlights from 2025 and What’s Ahead in 2026
Dear Biginners, Wishing you a very happy New Year! As we stand at the cusp of endless possibilities in 2026, we would like to take a moment to reflect on what we achieved together in 2025. Your continued support, thoughtful feedback, and kind words ofSend Supervisor Rule Emails Within Ticket Context in Zoho Desk
Dear Zoho Desk Team, I hope this message finds you well. Currently, emails sent via Supervisor Rules in Zoho Desk are sent outside of the ticket context. As a result, if a client replies to such emails, their response creates a new ticket instead of appendingZoho Desk - Change Time Zone for all users and set default for new user
Hi, Is there a way to set a default time zone so that when user creates an account via the Zoho Desk invitation, they don't need to select the time zone via the hundreds of choice? And, for already created users, can we edit the incorrect time zone selected by the user at the account creation ? Thanks ! FredAllow Manual Popup Canvas Size Control
Hello Zoho PageSense Team, We hope you're doing well. We would like to request an enhancement to the PageSense popup editor regarding popup sizing. Current Limitation: Currently, the size (width and height) of a popup is strictly controlled by the selectedWhy does Zoho’s diff viewer highlight parts of unchanged lines?
Hi everyone, I’ve noticed something odd in the Zoho editor’s diff view. When I delete a single line, the diff doesn’t just mark that line as removed. Instead, it highlights parts of the next line as if they changed, even though they are identical. Example:Introducing Assemblies and Kits in Zoho Inventory
Hello customers, We’re excited to share a major revamp to Zoho Inventory that brings both clarity and flexibility to your inventory management experience! Presenting Assemblies and Kits We’re thrilled to introduce Assemblies and Kits, which replaces theAssign Income to Project Without Invoice
Hello, Fairly new user here so apologies if there is a really obvious solution here that I am just missing... I have hundreds of small deposits into a bank account that I want to assign to a project but do not want to have to create an invoice every timeAutomating Employee Birthday Notifications in Zoho Cliq
Have you ever missed a birthday and felt like the office Grinch? Fear not, the Cliq Developer Platform has got your back! With Zoho Cliq's Schedulers, you can be the office party-cipant who never forgets a single cake, balloon, or awkward rendition ofNext Page