Kaizen #13 - Bulk Write API

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?
  1. When you want to insert, update, or upsert more than 100 records per API call. 
  2. 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:

  1. Prepare your CSV file
  2. Upload your file
  3. Create a bulk write job
  4. Check the job status
  5. 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:
  1. To give multiple values for a multi-select pick list field, enclose them in double quotes("") and separate each value with the semicolon(;).
  2. 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
Your zgid which you get from the organization API.




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": {
        "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": {
    "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. 
  • "type" with value "data "
  • "module"- It is the module (API name) you want to write the data in, from the uploaded CSV file.  Refer to the module metadata for more details.
  • "file_id" - It is the file ID obtained in the previous step.
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. 
Using field metadata API, you can get which fields can be set as unique fields in the CRM.



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

  1. The status can be either ADDED, INPROGRESS, or COMPLETED. Only the COMPLETED jobs will have the "download-URL" key in the response. 
  2. 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": {
  },
  "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!
        Previous 'Kaizen' - Bulk Read API
        Next 'Kaizen' - Notification API



    • 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 FAQs

    • Kaizen #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

    • Searching customer field

      Hello, When entering a receipt, we select customer information. The customer information is synced with Zoho CRM. However, we can't find the customer information because it searches for words that begin with the entered value. It needs to search for words

    • How I set default email addresses for Sales Orders and Invoices

      I have customers that have different departments that handle Sales Orders and Invoices. How can i set a default email for Sales Orders that's different than the default email for Invoices? Is there a way I can automate this using the Contact Persons Departments

    • Modular Permission Levels

      We need more modular Permissions per module in Books we have 2 use cases that are creating problems We need per module export permission we have a use case where users should be able to view the sales orders but not export it, but they can export other

    • Kaizen #157: Flyouts in Client Script

      Hello everyone! Welcome back to another exciting edition of our Kaizen series, where we explore fresh insights and innovative ideas to help you discover more and expand your knowledge!In this post, we'll walk through how to display Flyouts in Client Script

    • How get stock name from other column ?

      How get stock name from other column ? e.g. =STOCK(C12;"price") where C12 is the code of the stock

    • Adding a developer for editing the client application with a single user license

      Hi, I want to know that I as a developer I developed one application and handed over to the customer who is using the application on a single user license. Now after6 months customer came back to me and needs some changes in the application. Can a customer

    • Download an email template in html code

      Hello everyone, I have created an email template and I want to download it as html. How can i do that? I know you can do it via the campaigns-first create a campaign add the template and download it as html from there. But what if i don't want to create

    • Attachment is not included in e-mails sent through Wordpress

      I have a Wordpress site with Zeptomail Wordpress plugin installed and configured. E-mails are sent ok through Zeptomail but without the included attachment (.pdf file) Zeptomail is used to send tickets to customers through Zeptomail. E-Mails are generated

    • Upcoming Changes to the Timesheet Module

      The Timesheet module will undergo a significant change in the upcoming weeks. To start with, we will be renaming Timesheet module to Time Logs. This update will go live early next week. Significance of this change This change will facilitate our next

    • Best way to schedule bill payments to vendors

      I've integrated Forte so that I can convert POs to bills and make payments to my vendors all through Books. Is there a way to schedule the bill payments as some of my vendors are net 30, net 60 and even net 90 days. If I can't get this to work, I'll have

    • Cant update image field after uploading image to ZFS

      Hello i recently made an application in zoho creator for customer service where customers could upload their complaints every field has been mapped from creator into crm and works fine except for the image upload field i have tried every method to make

    • Billing Management: #4 Negate Risk Free with Advances

      In the last post, we explored how unbilled charges accumulate before being invoiced. But what happens when businesses need money before service begins? Picture this: A construction company takes on a $500,000 commercial building project expected to last

    • Is there an equivalent to the radius search in RECRUIT available in the CRM

      We have a need to find all Leads and/or Contacts within a given radius of a given location (most likely postcode) but also possibly an address. I was wondering whether anyone has found a way to achieve this in the CRM much as the radius search in RECRUIT

    • Zoho CRM Inventory Management

      What’s the difference between Zoho CRM’s inventory management features and Zoho Inventory? When is it better to use each one?

    • Cannot Enable Picklist Field Dependency in Products or Custom Modules – Real Estate Setup

      Hello Zoho Support, I am configuring Zoho CRM for real estate property management and need picklist field dependency: What I’ve tried: I started by customizing the Products module (Setup > Modules & Fields) to create “Property Type” (Housing, Land, Commercial)

    • Get Workflow Metadata via API

      Is there a way to get metadata on workflows and/or custom functions via API? I would like to automatically pull this information. I couldn't find it in the documentations, but I'm curious if there is an undocumented endpoint that could do this. Moderation

    • Zoho Projects - Q2 Updates | 2025

      Hello Users, With this year's second quarter behind us, Zoho Projects is marching towards expanding its usability with a user-centered, more collaborative, customizable, and automated attribute. But before we chart out plans for what’s next, it’s worth

    • FSM setup

      So we have been tinkering with FSM to see if it is going to be for us. Now is the time to bite the bullet and link it to our zoho books and zoho crm. The help guides are good but it would really help if they were a bit more in depth on the intergrations.

    • Upcoming Updates to the Employees Module in Zoho Payroll (US)

      We've made a couple of updates to the Employees module in Zoho Payroll (latest version of the US edition). These changes will go live today. While creating an employee Currently, the Compensation Details section is part of the Basic Details step, where

    • Possible to Turn Off Automatic Notifications for Approvals?

      Hello, This is another question regarding the approval process. First a bit of background: Each of our accounts is assigned a rank based on potential sales. In Zoho, the account rank field is a drop-down with the 5 rank levels and is located on the account

    • ZOHO Creator subform link

      Dear Community Support, I am looking for some guidance on how to add a clickable link within a Zoho Creator subform. The goal is for this link to redirect users to another Creator form where they can edit the data related to the specific row they clicked

    • Allow Resource to Accept or Reject an Appointment

      I have heard that this can be done, is there any documentation on how?

    • Create new Account with contact

      Hi I can create a new Account and, as part of that process, add a primary contact (First name, last name) and Email. But THIS contact does NOT appear in Contacts. How can I make sure the Contact added when creating an Account is also listed as a Contact?

    • Custom Fonts in Zoho CRM Template Builder

      Hi, I am currently creating a new template for our quotes using the Zoho CRM template builder. However, I noticed that there is no option to add custom fonts to the template builder. It would greatly enhance the flexibility and branding capabilities if

    • Python - code studio

      Hi, I see the code studio is "coming soon". We have some files that will require some more complex transformation, is this feature far off? It appears to have been released in Zoho Analytics already

    • Sync desktop folders instantly with WorkDrive TrueSync (Beta)

      Keeping your important files backed up and accessible has never been easier! With WorkDrive desktop app (TrueSync), you can now automatically sync specific desktop folders to WorkDrive Web, ensuring seamless, real-time updates across devices. Important:

    • How To Insert Data into Zoho CRM Organization

      Hi Team I have this organization - https://crm.zoho.com/crm/org83259xxxx/tab/Leads I want to insert data into this Leads module, what is the correct endpoint for doing so ? Also I have using ZohoCRM.modules.ALL scope and generated necessary tokens.

    • Where can I get Equation Editor por Zoho Writer?

      I need to use Math Formulas in my document. Thank you.

    • How can I get base64 string from filecontent in widget

      Hi, I have a react js widget which has the signature pad. Now, I am saving the signature in signature field in zoho creator form. If I open the edit report record in widget then I want to display the Signature back in signature field. I am using readFile

    • Creator roadmap for the rest of 2022

      Hi everyone, Hope you're all good! Thanks for continuing to make this community engaging and informative. Today we'd like to share with you our plans for the near future of Creator. We always strive to strike a good balance of features and enhancements

    • Filtering repport for portal users

      Salut, I have a weird problem that I just cannot figure out : When I enter information as administrator on behalf of a "supplier" portal user (in his "inventory" in a shared inventory system), I can see it, "customer" portal users can see it, but the

    • Zoho Inventory. Preventing Negative Stock in Sales Orders – Best Practices?

      Dear Zoho Inventory Community, We’re a small business using Zoho Inventory with a team of sales managers. Unfortunately, some employees occasionally overlook stock levels during order processing, leading to negative inventory issues. Is there a way to

    • Integración Books para cumplir la ley Crea y Crece y Ley Antifraude (VeriFactu)

      Hola: En principio, en julio de 2025, entra en vigor la ley Crea y Crece y Ley Antifraude (VeriFactu). ¿Sabéis si Zoho va a cumplir con la ley para cumplir con la facturación electrónica conectada a Hacienda? Gracias

    • Zoho One - Syncing Merchants and Vendors Between Zoho Expense and Zoho Books

      Hi, I'm exploring the features of Zoho One under the trial subscription and have encountered an issue with syncing Merchant information between Zoho Expense and Zoho Books. While utilizing Zoho Expense to capture receipts, I noticed that when I submit

    • Is Zoho Sheet available for Linux ?

      Is Zoho Sheet available for Linux ?

    • Zoho Sheet for Desktop

      Does Zoho plans to develop a Desktop version of Sheet that installs on the computer like was done with Writer?

    • Create static subforms in Zoho CRM: streamline data entry with pre-defined values

      Last modified on (9 July, 2025): This feature was available in early access and is currently being rolled out to customers in phases. Currently available for users in the the AU, CA, and SA DCs. It will be enabled for the remaining DCs in the next couple

    • BUTTONS SHOWN AS AN ICON ON A REPORT

      Hi Is there any way to create an action button but show it as an icon on a report please? As per the attached example? So if the user clicks the icon, it triggers an action?

    • Dropshipping Address - Does Not Show on Invoice Correctly

      When a dropshipping address is used for a customer, the correct ship-to address does not seem to show on the Invoice. It shows correctly on the Sales Order, Shipment Order, and Package, just not the Invoice. This is a problem, because the company being

    • RFQ MODEL

      A Request for quotation model is used for Purchase Inquiries to multiple vendors. The Item is Created and then selected to send it to various vendors , once the Prices are received , a comparative chart is made for the user. this will help Zoho books

    • Next Page