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

    • Clone a Module??

      I am giong to repurpose the Vendors module but would like to have a separate but very similar module for another group of contacts called Buyers. I have already repurposed Contacts to Sellers. Is it possible to clone (make a duplicate) module of Vendors

    • Advance PDF creation from CRM data

      I'm trying to create a PDF export of data in the CRM. My problem is I want a pretty complicated format for the data. I'm trying to export multiple modules worth of data, with nested one-to-many relationships between the modules. Along with that, I want

    • How to change the text in WhatsApp Zobot integrated to Zoho Booking?

      I have integrated Zoho Bookings into Zoho SalesIQ, I want to change the text in WhatsApp when creating a booking in Zobot how to change those text?

    • Updating Subform Record from other Form

      Just wanted to ask how to properly approach this. I have 2 forms and would like to trigger an auto update on the subform once record submitted. block below only updates 1 row for each recordRow in input.AV_System { AssetRecord = Site_Asset_Services[SOR_No

    • Zoho Books - Hide Convert to Sales Order if it can't be used.

      Hi Books team, I noticed that it is not possible to convert a Quote to a Sales Order when a Quote is not yet marked as accepted. My idea is to not show the Convert to Sales Order button when it is not possible to use it, or show it in a grey inactive

    • How do I bulk archive my projects in ZOHO projects

      Hi, I want to archive 50 Projects in one go. Can you please help me out , How can I do this? Thanks kapil

    • Cross-Data Center Collaboration and / Or allowing users to choose DC

      Dear Zoho Cliq Support Team, We are writing to request a significant enhancement to Zoho Cliq that would greatly benefit our geographically dispersed development team. Current Challenge: Currently, Zoho Cliq automatically routes users to specific data

    • New Mandatory One-Click Unsubscribe Link Overshadowing Custom Unsubscribe Link

      I was recently informed by Zoho CRM Support that they are now mandated by the large email service providers like Google and Yahoo to provide a one-click unsubscribe option in the header (not the body) of all mass emails. I have a custom unsubscribe link

    • Send / Send & Close keyboard shortcuts

      Hello! My team is so close to using Zoho Desk with just the keyboard. Keyboard shortcuts really help us to be more efficient -- saving a second or two over thousands of tickets adds up quickly. It seems like the keyboard shortcuts in Desk are only for

    • Is it possible to register webhooks in Zoho CRM using API?

      Hello, I am trying to register a webhook in Zoho CRM programmatically (using the API). Specifically, I want to register a webhook that is fired when new Contacts are created in the CRM. I was able to setup a webhook using the UI, by creating a rule that

    • Calls where the local audio is shared, have echo

      When another user is sharing their screen with audio, I get echo from my own voice. We tested this with multiple users, with different audio setups, and there's no obvious way to fix it. Is this a bug you could look into, or are we missing something?

    • Update application by uploading an updated DS file

      Is it possible? I have been working with AI on my desktop improving my application, and I have to keep copy pasting stuff... Would it be possible to import the DS file on top of an existing application to update the app accordingly?

    • Markdown support, code cells...

      Hi Zoho I'd like to vote for a feature that markdown is supported with: Headings Code highlighting Quoteblocks ... Furthermore a inline card(like inline sketch card) for special text like Code would be great. And just to add my vote as well for "Tags"!

    • Minimise chat when user navigates to new page

      When the user is in an active chat (chatbot) and is provide with an internal link, when they click the link to go to the internal page the chat opens again. This is not a good user experience. They have been sent the link to read what is on the page.

    • How do I fix this? Unable to send message; Reason:554 5.1.8 Email Outgoing Blocked.

      How do I fix this? Unable to send message; Reason:554 5.1.8 Email Outgoing Blocked.

    • Reports: Custom Search Function Fields

      Hi Zoho, Hope you'll add this into your roadmap. Issue: For the past 2yrs our global team been complaining and was brought to our attention recently that it's a time consuming process looking/scrolling down. Use-case: This form is a service report with

    • Zoho Projects app update: Voice notes for Tasks and Bugs module

      Hello everyone! In the latest version(v3.9.37) of the Zoho Projects Android app update, we have introduced voice notes for the Tasks and Bugs module. The voice notes can be added as an attachment or can be transcribed into text. Recording and attaching

    • zurl URL shortener Not working in Zoho social

      zurl URL shortener Not working in while creating a post in Zoho social

    • In the Zoho CRM Module I have TRN Field I should contain 15 digit Number , If it Contain less than 15 digit Then show Alert message on save of the button , If it not contain any number not want to sh

      Hi In the Zoho CRM Module I have TRN Field I should contain 15 digit Number , If it Contain less than 15 digit Then show Alert message on save of the button , If it not contain any number not want to show alert. How We can achive in Zoho CRm Using custom

    • Power of Automation::Streamline log hours to work hours upon task completion.

      Hello Everyone, A Custom Function is a user-written set of code to achieve a specific requirement. Set the required conditions needed as to when to trigger using the Workflow rules (be it Tasks / Project) and associate the custom function to it. Requirement:-

    • Zoho Bookings know-how: A hands-on workshop series

      Hello! We’re conducting a hands-on workshop series to help simplify appointment scheduling for your business with Zoho Bookings. We’ll be covering various functionalities and showing how you can leverage them for your business across five different sessions.

    • Custom report

      Hello Everyone I hope everything is fine. I've tried to To change the layout of the reports, especially the summary page report, and I want to divide summary of each section in the survey but I can't For example: I have a survey containing five different

    • Zoho Journey - ZOHO MARKETING AUTOMATION

      I’ve encountered an issue while working with a journey in Zoho Marketing Automation. After creating the journey, I wanted to edit the "Match Criteria" settings. Unfortunately: The criteria section appears to be locked and not editable. I’m also unable

    • Custom Fields in PDF outputs

      I created a couple of custom fields. e.g Country of Origin and HS Tariff Code. I need these to appear on a clone of a sales order PDF template but on on the standard PDF template. When I select "appear on PDFs' it appears on both but when I don't select

    • How to create a Service Agreement with Quarterly Estimate

      Hello, I'm not sure if this has been asked before so please don't get mad at me for asking. We're an NDIS provider in Australia so we need to draft a Service Agreement for our client. With the recent changes in the NDIS we're now required to also include

    • Change Currency symbol

      I would like to change the way our currency displays when printed on quotes, invoices and purchase orders. Currently, we have Australian Dollars AUD as our Home Currency. The only two symbol choices available for this currency are "AU $" or "AUD". I would

    • Zoho Social - Post Footer Templates

      As a content creator I often want to include some information at the end of most posts. It would be great if there was an option to add pre-written footers, similar to the Hashtag Groups at the end of posts. For example, if there is an offer I'm running

    • Allow to pick color for project groups in Zoho Projects

      Hi Zoho Team, It would be really helpful if users could assign colors to project groups. This would make it easier to visually distinguish groups, improve navigation, and give a clearer overview when managing multiple projects. Thanks for considering

    • Zoho Books - Quotes to Sales Order Automation

      Hi Books team, In the Quote settings there is an option to convert a Quote to an Invoice upon acceptance, but there is not feature to convert a Quote to a Sales Order (see screenshot below) For users selling products through Zoho Inventory, the workflow

    • Can't find imported leads

      Hi There I have imported leads into the CRM via a .xls document, and the import is showing up as having been successful, however - when I try and locate the leads in the CRM system, I cannot find them.  1. There are no filters applied  2. They are not

    • Custom Button Disappearing in mobile view | Zoho CRM Canvas

      I'm working in Zoho CRM Canvas to create a custom view for our sales team. One of the features I'm adding is a custom button that opens the leads address in another tab. I've had no issue with this in the desktop view, but in the mobile view the button

    • The connected workflow is a great idea just needs Projects Integrations

      I just discovered the connected workflows in CRM and its a Great Idea i wish it was integrated with Zoho Projects I will explain our use case I am already trying to do something like connected workflow with zoho flow Our requirement was to Create a Task

    • Zoho Projects MCP Feedback

      I've started using the MCP connector with Zoho Projects, and the features that exist really do work quite well - I feel this is going to be a major update to the Zoho Ecosystem. In projects a major missing feature is the ability to manage, (especially

    • email template

      How do I create and save an email template

    • Enhancements in Portal User Group creation flow

      Hello everyone, Before introducing new Portal features, here are some changes to the UI of Portals page to improve the user experience. Some tabs and options have been repositioned so that users can better access the functionalities of the feature. From

    • How do I filter contacts by account parameters?

      Need to filter a contact view according to account parameter, eg account type. Without this filter users are overwhelmed with irrelevant contacts. Workaround is to create a custom 'Contact Type' field but this unbearable duplicity as the information already

    • Can I add Conditional merge tags on my Templates?

      Hi I was wondering if I can use Conditional Mail Merge tags inside my Email templates/Quotes etc within the CRM? In spanish and in our business we use gender and academic degree salutations , ie: Dr., Dra., Sr., Srta., so the beginning of an email / letter

    • email moderation issue when email is sent in the name of a mail group

      Symptom: an email that is sent by a mail group moderator in the name of a moderated mail group is held back for approval. Reproduction: Create a moderated mail group with members and moderators. Allow that mails can be sent in the name of the group (extended settings). Send an email to the group as a group moderator, but in the name of the group. This mail is held back for moderation which is unexpected. Expected: A mail sent by group moderator to a moderated group are not held back for moderation

    • blank page after login

      blank page after logging into my email account Thanks you

    • Always display images from this sender – Is this feature available?

      In Zoho mail, I had my "Load external images" setting set to "Ask me", and that's fine. That's the setting I prefer. What's not fine though is I always need to tick "Display now" for each email I get, regardless if I've done that multiple times from several

    • Next Page