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
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
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! CommandsKaizen #165 : How to call Zoho CRM APIs using Client Script
Welcome back to another exciting Client Script post! In this post, we will discuss one of the most frequently asked questions: How do you call Zoho CRM APIs from Client Scripts? In this kaizen post, 1. Ways to make calls to Zoho CRM APIs using ClientKaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provideExtension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use APIKaizen #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 achieved
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho DataPrep Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho Campaigns 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 One - White Label
Releasing a white-label feature for Zoho One, or any software or service, can offer several advantages and benefits for both the company providing the software (Zoho in this case) and its users. Here are some key reasons for releasing a white-label featureMissing parameters in request, any way i can figure out what parameters i need to add?
const url = "https://people.zoho.com/people/api/forms/json/P_Task/insertRecord"; const inputData = { "Status": "Open", "Description": "Task to set up and configure Zoho Mail on desktop application.", "CreatedTime": "01-Jan-2025 10:30 AM", "Due_Date":Address Grabber function for Zoho
I converted from ACT to Zoho. With ACT, I used an add-on called AddressGrabber to scrape the contact information from leads that I buy and contact information contained on emails and websites and directly add it as a new lead or contact. Does anyone knowCan you modify "Last Activity Time" in deluge? If so what's the field name?
I need to perform some bulk modifications on records in the Leads module, but I need to avoid changing the "last activity time" or "date modified" because I am using those fields to filter and sort leads for follow-up action. I cannot find an answer anywhereRunning Total % in Pivot with filters
Hi there, I have seen a few posts on this topic, but i cant seem to find one that will work when applyig filters to the data. I have Rows and Data in a pivot view I want to show the running total of revenue as a % of the total for the data set. If i addIncluded in Zoho One?
Will LandingPage eventually be included in Zoho One?Add an "Impersonate" feature to Zoho Projects
It would be nice to have an "impersonate" feature added to Zoho Projects that would allow administrators to impersonate employees to enable administrators to see for themselves what employees can and cannot see in the system. I am aware of all of theReports - custom layout - duplicate report
Do you also have this problem and what is the possible solution? I duplicate a report that has a "custom layout". Unfortunately the custom layout is not duplicated. To be improved for a future release by Zoho. I export the custom layout and import it...Select CRM Custom Module in Zoho Creator
I have a custom module added in Zoho CRM that I would like to link in Zoho creator. When I add the Zoho CRM field it does not show the new module. Is this possible? Do i need to change something in CRM to make it accesible in Creator?GROUPING OF CUSTOMER
SIR PLEASE ADD GROUPING OF CUSTOMER IN ZOHO BOOKSZoho LandingPage is integrated with Zoho One!
Greetings to the Zoho One users out there! We're delighted to let you know that Zoho LandingPage is available in Zoho One too! With Zoho LandingPage, you can host custom-made landing pages, and persuade the visitors to dive deeper by making further clicks,2024 Wrap: Rediscover these features and enhancements in Zoho CRM
Hello everyone! I wish all of you a joyful and prosperous 2025! As we welcome 2025, I’m excited to share a recap of the year 2024 and highlight some of the coolest new features and enhancements we’ve added to the Zoho CRM platform. Last year, we announcedAllow "add new" option to picklists and multiselection fields from add or edit pages
Hello zoho, please insert an add option (ie +)sign) to pick and multiselect fields so we can add new options while entering or editing records. For example. in my lead module, while adding a new record, I realized I had a new lead source. I went to myA quicker way to provide accountants access to Zoho Books, similar to Xero and Quickbooks
Hey guys, I'm finding the procedure to give access to an external accountant to Zoho Books less than ideal. Having to create an account by Zoho instead of myself, and then wait for it to be given a license to then pass to the accountant seems a bit timeThis user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details
Hello, Just signed up to ZOHO on a friend's recommendation. Got the TXT part (verified my domain), but whenever I try to add ANY user, I get the error: This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details I have emailed as well and writing here as well because when I searched, I saw many people faced the same issue and instead of email, they got a faster response here. My domain is: raisingreaderspk . com Hope this can be resolved. Thank youThis mobile number has been marked spam. Please contact support.
Hi Support, Can you tell me why number was marked as spam. I have having difficult to add my number as you keep requesting i must use it. My number is +63....163 Or is Zoho company excluding Philippines from their services?Update Candidate Status Through Workflow in Blueprint
Hi Team, We have a blueprint built out with custom functions that update particular fields based on candidate actions. When particular fields are updated we need to move the candidate forward in the blueprint. We tried to do this through a workflow,Zoho Canned respond do have a huge lag issue.
Previously the Zoho canned respond works perfectly ... on once server update and all the Canned respond enconter huge lag... in the end cause most of the canned respond just shown code with /xxx and not the sentence....Pay Contractor Timesheets
I have contractors that fill out a timesheet. Each hour must be assigned to a current client. I need the easiest way to get the contracts paid. They are paid on an hourly bases. How can this be done?ShipStation and Zoho Inventory
Hello, I am looking to sync zoho inventory with shipstation ZOHO INVENTORY SHIP STATION Sales Order ==> create ORDERS INVOICE <== Shipments What exactly does BETA mean on the Shipstation connector? This is required for me to sign-on in the next month. Thanks in advance for your effortsSaving slide elements
I have created grouped items including text and animation that I want to use in later slides. (Like an animated logo) Is there a way to save these grouped elements in my library?Are downloadable product available in Zoho Commerce
Hi all. We're considering switching to Zoho Commerce for our shop, but we sell software and remote services. Is there a features for downloadable products? I can't find any information about this. Thank you very much AliceFunction #10: Update item prices automatically based on the last transaction created
In businesses, item prices are not always fixed and can fluctuate due to various factors. If you find yourself manually adjusting the item rates every time they change, we have the ideal time-saving solution for you. In today's post, we bring you customMove site from WIX to ZOHO Sites
I have a simple website on WIX. I am wondering if someone is available to help me move this website - https://www.videothreezero.com/ to ZOHO. Michael Bostonzoho calendar week view - "super compact by default"
every time i go to my calendar i have to re-engage the "super-compact view" for the week view...is there a way to make "super-compact" a default view so I dont have to keep on setting it manually?Change work hours per day for employees
Hello, Is there a way to modify the work hours per day for employees in Zoho projects? This would be helpful for resource allocation to more accurately see when an employee who works 35 hours a week vs 40 hours has a full schedule. Thanks.Zoho CRM Automation Help: Send Email When Fault is Marked as Done & Module Relationships
Hi everyone, I have the following User-Created Modules in Zoho CRM: Clients Assets Faults Handymen Every client can have multiple assets. Every asset can have multiple faults. Every fault is assigned to one handyman. What I Want to Achieve: ✅ I want toAdding New Domain to Zoho mail
Hi, I have one Zoho account already called for example "Awesome Animals". Under this account I have one domain already setup with zoho mail, example: - awesomecats.com I have another website as well which I want to add under this "Awesome Animals" account,I cannot receive emails.
I need help, I've tried everything but I still can't receive emails from other people. I can send it but I can't receive emails, When I created the email it was all in order and suddenly I can't get emails from anyone anymore.Incoming Gmail Email Not Coming Into Zoho
My outbound email from Zoho is working, but when people respond to the email, it's not coming back into Zoho. I can see it when I'm in Gmail, but it's not in Zoho.Não foi possível enviar a mensagem;Razão:554 5.1.8 Email Outgoing Blocked.
Preciso de ajuda não consigo enviar emails,conta recen criadaExpand Zia's Language Support and AI Capabilities
Dear Zoho Desk Support, I would like to submit a feature request to improve Zia, the AI-driven support assistant in Zoho Desk. Currently, Zia only supports the English language, while other AI agents such as Gemini, ChatGPT, and Claude can work with aAverage Costing / Weighted Average Costing
Hello fellow maadirs. I understand Zoho Books uses FIFO method of dealing with inventory costing, but do you guys have any plans to introduce average costing? We indians need average costing. It's part of our culture. Please. I beg thee. Thanks.Links in Instagram
Hi there, I have been using Later for a while now but keen to come back to Zoho Social as Later doesn't offer tagging of pages on Facebook but they offer something Zoho doesn't. You can add a link to your bio which opens up your profile feed where imagesCredit note
By mistake I issued credit note in Jan 2025 for the invoice related to Dec 2024. Now I want to delete this credit note but anable to do so. Need help in thisHow to query for Deals record based on Pipeline?
I want to query for Deals records that matches a specified Pipeline using a Deluge function. When I call zoho.crm.searchRecords("Deals","(Pipeline:equals:" + myPipeline + ")"), I get this error: { code: 'INVALID_QUERY' , details: {...} , message: 'InvalidCRM formula field help
Hello! i was hoping to get some help with a formula i'm creating within a module. I'm looking to make a formula that changes based on a date field but based upon the present date. This is the formula i have so far: If(Now() < ${Instructors.Start Date},Change to copy/paste functionality in Deluge code editor
Recently there was a change to the Deluge code etidor where it now inserts backslashes into strings automatically when copying/pasting strings with double quotes, it's a nightmare to have to go delete all these. Is it possible to toggle this on or off?ChatGPT only summarize in English
Hello i' v enabled chatgpt in salesIQ, it works great inside conversation (revise, Rephrase etc) add tags works well with another language than English. But when I want to summarize it render only in English, despite sales IQ is set to another language.Chart with Filtered Data vs Unfiltered Data
I am looking to create a chart view that displays the full data set vs a subset of the data filtered by user filter. However I do not seem to find any method by which to exclude a plot from the applied filter or any other method by which to display theNext Page