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

    • Zoho Meeting Plug compatibility with newer versions of Outlook

      Documentation states that the zoho meeting plug in for outlook is only compatible with versions up to Outlook 2019 What is available to users of more up to date versions of outlook/office 365?

    • Getting Attachments in Zoho Desk via API

      Is there a way to get attachments into Zoho Desk via an API?      We have a process by which a zoho survey gets sent to the user as a link in a notification.    The survey has several upload fields where they can upload pdf documents.    I've created

    • Introducing Zoho's own SMS gateway

      We're thrilled to announce the launch of our own SMS gateway feature within Zoho Marketing Automation! This new feature enables seamless SMS campaign management alongside your email marketing initiatives, providing a more integrated and efficient way

    • Embedding in Desk articles

      We would like to embed documents in our Desk articles. When we use an iframe for the embed, we get scrollbars and a frame border. Neither of those is acceptable. I've spoken with the Desk Support team about what we want and they tell me that it cannot

    • Zoho CRM button to download images from image upload field

      Hello, I am trying to create a button in Zoho CRM that I can place in my record details view for each record and use it to download all images in the image upload fields. I tried deluge, client scripts and even with a widget, but feel lost, could not

    • Mass Update Contacts In Zoho Campaigns

      Is there a way to mass update contacts in zoho campaigns? I want to be able to change the content of a field for a few hundred contacts, and can't go through all of them individually.

    • report showing assignment type

      Hi, We've created a number of workflows to allow us to auto assign tickets to agents based on keywords and other criteria. I'm struggling to create a report that would show me what is the percentage of tickets that are assigned automatically via workflows

    • Option to Disable Knowledge Base Section in Feedback Widget Popup Hello Zoho Desk Team

      Hello Zoho Desk Team, How are you? We are actively using Zoho Desk and would like to make more use of the Feedback Widget. One of the ways we implement it is through the popup option. At the moment, the popup always displays the Knowledge Base section,

    • Placeholders in Ticket Templates

      We should be able to use placeholders in ticket templates. When we create a new ticket, our description field is shown to the client in the email they receive.  It would be very handy to be able to personalize that description field in our ticket templates to pull in the name of the client that the ticket is for. Using them in the subject field as well, so we can auto populate Account Names, etc. 

    • when the record is created the tag want to Show as Opportunity how i achive this using Deluge Script

      In the quotation i have the work flow schedule for create opportunity record in the module , on that time the quotation tag select as opportunity created. How i achive this using Deluge Script . this like i want to Do tag1 = Map(); tag1.put("name","Nurturing

    • Delete a channel

      I need delete a channel in tickets.

    • Copy / Duplicate Workflow

      I have workflows setup that are very similar to each other. We have a monitoring system watching servers, and all notifications - no matter what client it is about - will come from a  noreply@ address which is not very helpful in having it auto assigned to the right account. I have setup a workflow that will change the contact name of the ticket (currently it would say noreply@) to the correct customer which is based on the subject line, as that mentions which server the alert it is about. I need

    • Subtasks don't update parent task's times

      Hi there: I've recently upgraded to premium and check that subtasks completion % don't update the proportional completion of the parent tasks related to it.  We've been challenging with the problem of having to update twice or sometimes 3 times the completion of the related tasks. I've seen posts similar to this, of 3 years old.  Is there any roadmap for making this happen in a future release? Thanx César Ratto Lima, Perú.

    • Should I Use DMARC?

      When I configure Zoho Mail's DMARC settings, it's mandatory to fill in the RUA and RUF (Aggregate notification email address*, Forensic notification email address*) addresses. When we enter an email address in these fields, we receive reports from the

    • Mail ToDo & Tasks Webhooks

      Our company uses Zoho ToDo inside Mail to manage our tasks. When I create a task and assign it to a team member it does not notify them unless I add a reminder via mail. I'm trying to create a webhook for when a task is created to send a cliq message

    • Can't upload attachments.

      I can't upload attachment in Zoho Mail.

    • Tip #44 – Get Deeper Insights with Zoho Assist’s Custom Reports – ‘Insider Insights’

      In today’s fast-paced IT environment, having a clear view of your remote support activities is more important than ever. Zoho Assist’s Custom Reports feature gives IT teams the ability to generate tailored reports that provide actionable insights and

    • Message "...does not support more than 100 distinct values..." WHY????

      I get this message on one of my reports: Sorry, Zoho Reports currently does not support more than 100 distinct values in columns. 'Account Name * Sum(Amount),Count(Amount Tier)' contains more than 100 distinct values.  Possibly, you can apply filter to reduce the number of distinct values in 'Account Name' or drop the 'Account Name' field in Rows. I want to list all ACCOUNT NAMES (about 500) with SALES BY ACCOUNT.  What is blocking this?

    • Need Easy Way to Update Item Prices in Bulk

      Hello Everyone, In Zoho Books, updating selling prices is taking too much time. Right now we have to either edit items one by one or do Excel export/import. It will be very useful if Zoho gives a simple option to: Select multiple items and update prices

    • Let's Talk Recruit: Super-charge hiring with Zoho Recruit add-ons

      Welcome back to our Let’s Talk Recruit series! This time, we’re diving into something that might seem like a small upgrade but has a huge impact on recruiter productivity: Zoho Recruit add-ons. Think about how much of your day is spent in your inbox or

    • Vendor Signatures Needed for Purchase Orders

      Hello everyone, We have a unique requirement that necessitates that Vendors & Suppliers formally acknowledge our Purchase Orders upon receipt. I was hoping that there would be an option to do so in Zoho Books, but that does not appear to be the case.

    • Is there an API to "File a Ticket" in Desk

      Hi, Is there an API to "File a Ticket" in Desk to zoho projects?

    • Store "Sign in with Google/Microsoft/GitHub etc." details

      Quite often now, users are using a sign-in provider like Google or Microsoft to sign into various apps and services. It would be great if Vault could remember which providers you use for each website and sign you in with that provider instead of a username

    • Critical Issue: Tickets Opened for Zoho Support via the Zoho Help Portal Were Not Processed

      Hi everyone, We want to bring to your attention a serious issue we’ve experienced with the Zoho support Help Portal. For more than a week, tickets submitted directly via the Help Portal were not being handled at all. At the same time no alert was posted

    • Tip of the Week #72– Assign thread ownership to avoid confusion.

      When teams handle a large volume of emails, managing threads becomes important to stay organized. Without a clear system, duplicate replies, missed follow-ups, or confusion over responsibilities can happen. Thread assignment solves this by designating

    • Unarchive tickets

      How can I manually unarchive tickets?

    • Optimize your Knowledge Base for enhanced accessibility by adding alt tags for images

      Let's learn why alt tags are crucial for your articles. You can add alternative tags (alt tags) and alternative text (alt text) to the images you share on your community forums or when embedding them in articles. Alt tags refer to the HTML attribute,

    • FSM trying again

      have not linked FSM yet to the rest of out Zoho suit. It certainly looks like the apointment and service part is more manageable for our staff. The question is that our engineers multi task examples 1. deliver products to customers not fitted 2. Service

    • Feature Request: Conditional Field Mandatoriness Based on Display Status

      Hello Zoho Creator Team, I would like to suggest an enhancement to improve the flexibility of form validations. Currently, when we need a field to be mandatory only if it's displayed on the form, the only option is to: Set the field as not mandatory in

    • Data Migration Strategies for Moving to a Cloud Solution

      Hi everyone, I’ve been working on moving some of our critical systems, including CRM and project data, to a Zoho cloud solution, and one of the biggest challenges I’ve encountered is data migration. Transferring large volumes of data while keeping it

    • Commerce Order as Invoice instead of Sales Order?

      I need a purchase made on my Commerce Site to result in an Invoice for services instead of a Sales Order that will be pushed to Books. My customers don't pay until I after I add some details to their transaction. Can I change the settings to make this

    • How to set different item selling prices for Zoho Commerce and Zoho Books

      Item selling prices for Zoho Commerce and Zoho Books are in sync. If we update the Item selling price in Books, the same will happen in commerce and vice versa. I need a separate commerce selling price for online users and a separate books selling price

    • Time Entry Notifications

      Hi All - I have support staff who place notes of their work in the time entry section of Zoho Desk. Is there a specific workflow or setting I need to enable to have the ticket holder updated via email when an entry is saved?

    • How to report 'Response violation' OR 'Resolution violation'

      Hi, I want to report on SLA Violation Type. I grouped my tickets on this column. It seems I only get 'Response and Resolution Violation' or 'Not Violated'. The former seems to be given to a ticket if only the Response Time was violated. I would expect

    • [Webinar] Automate sales and presales workflows with Writer

      Sales involves sharing a wide range of documents with customers across the presales, sales, and post-sales stages: NDAs, quotes, invoices, sales orders, and delivery paperwork. Generating and managing these documents manually slows down the overall sales

    • Power of Automation :: Quick way to associate your Projects with Zoho CRM

      A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automate complex tasks and

    • Date triggering Workflow rule

      I have a function triggered by a workflow rule. The function takes a date and creates a task for that date and fills in a field with the name of the day for that date. It also updates the status field of the record. The workflow rule is set to run whenever

    • Restricting contact creation

      Hi all! I am looking to use Zoho Desk in a part of the business that takes end user enquiries. These are generally single interactions, and not linked to an account name. As Desk is Account centric, has anyone designed a way to manage these incoming emails

    • Import Holiday Calendars

      HI Zoho Is there anyway of importing an online calendar like https://www.calendarlabs.com into the business hours calendars, to speed up setup of holiday calendars. Also could we also request a feature where you can specify a Holiday as hours, i.e it could be that the company is on a 1/2 day due to a holiday or when it is Eid in the UAE and they are only allowed to work restricted hours so we need the calendar to be flexible to allow for this. Regards Jamie

    • Filtering Tickets based on Email headers

      We're starting to get a lot more junk coming into our Zoho Desk, which is then triggering unnecessary email alerts to agents. Once thing we could do to cut this junk in half, is to filter tickets based on email headers. Any email containing the `List-Unsubscribe`

    • Next Page