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



    Access your files securely from anywhere



      Zoho Campaigns Resources

            Zoho Developer Community

                Bootcamp
                Community
                Pricing
                Webinars
                What's New
                Integrations
                Contact Support
                Contact Sales

                  Zoho Survey Resources
                    Features
                    Survey Templates
                    Integrations
                    Community
                    iOS Mobile Surveys
                    Pricing
                    Android Mobile Surveys
                    Insurvey Blogs
                    Insight Blogs
                    Tips & Tricks






                                  Latest Feature Updates


                                      Zoho Desk Resources

                                      • Desk Community Learning Series


                                      • Digest


                                      • Functions


                                      • Meetups


                                      • Kbase


                                      • Resources


                                      • Glossary


                                      • Desk Marketplace


                                      • MVP Corner


                                      • Word of the Day




                                          Zoho Marketing Automation
                                            Zoho SalesIQ Resources


                                                  Manage your brands on social media
                                                  Access Zoho Social

                                                    Zoho Pagesense Resources


                                                        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 CRM Resources

                                                                            • CRM Community Learning Series

                                                                              CRM Community Learning Series


                                                                            • Kaizen

                                                                              Kaizen

                                                                            • Functions

                                                                              Functions

                                                                            • Meetups

                                                                              Meetups

                                                                            • Kbase

                                                                              Kbase

                                                                            • Resources

                                                                              Resources

                                                                            • Digest

                                                                              Digest

                                                                            • CRM Marketplace

                                                                              CRM Marketplace

                                                                            • MVP Corner

                                                                              MVP Corner





                                                                                Design. Discuss. Deliver.

                                                                                Create visually engaging stories with Zoho Show.

                                                                                Get Started Now


                                                                                  Zoho Show Resources


                                                                                    Zoho Writer Writer

                                                                                    Get Started. Write Away!

                                                                                    Writer is a powerful online word processor, designed for collaborative work.

                                                                                      Zoho CRM コンテンツ






                                                                                        Nederlandse Hulpbronnen


                                                                                            ご検討中の方





                                                                                                  • Recent Topics

                                                                                                  • Create workflow rules based on notes

                                                                                                    Last modified on 17/04/2023: Creating Workflow rules based on notes is now available for all Zoho CRM users in all DCs. Note that it was an early access feature available only upon request. As of April 13, 2023, it is rolled out for al Zoho CRM accounts.

                                                                                                  • Workflow sync between zoho books and zoho inventory

                                                                                                    Hello, While the custom fields, validation rules and even custom buttons are sync'd between zoho books and zoho inventory, the workflow rules do not. Not sure if this is an intentional purpose of zoho team for some good reason or if it's in the development

                                                                                                  • HOW TO USE ZOHO

                                                                                                    IDK

                                                                                                  • Item sales account via api

                                                                                                    Hey everyone, I’m making an invoice using the create invoice endpoint on the api. Is it possible to set a sales account in the line_items attributes?

                                                                                                  • Zoho Please change your ways

                                                                                                    I started using Your new Zoho bookings in earnest 3 days ago. What a mistake.  Once again, everything is backwards and upside down.  I had to spend 5 hours testing how the thing works in order for me to understand how to acutally use it.  When i started using google calendar years ago.  it took seconds to figure out how it works. Why is that. bc they put everything in places where it makes sense.  Today, I needed to add an appointment as well as a time off.  Stupid me i added the time off first,

                                                                                                  • Make a ticket visible in the Community

                                                                                                    Hi there, It is possible to have a conversation with a customer via a ticket and eventually the proposed solution isn't possible yet. Therefore you want to add it as an idea in the Community, available and open to everyone that is in the community, so

                                                                                                  • Zoho email folders gone

                                                                                                    Hi, All my email folders are gone, i cant found any email, except sent. Also before folder rulesas was changed and i didnt fixed them, could you please check it?

                                                                                                  • Pause/Resume Subscrtiption API

                                                                                                    I don't see the option to Pause/Resume a subscription using the API, is it in the pipeline?

                                                                                                  • Update Department on Ticket (with applied Blueprint)

                                                                                                    Hello, Is it possible to update the Department of a ticket which is dictated by a blueprint, e.g. I would like to change departments at different states in the Blueprint. I do not see this is an option in workflow rules or blueprint transition actions,

                                                                                                  • ERROR_CODE :554, ERROR_CODE :rejected due to spam

                                                                                                    Please verify bounce message: This message was created automatically by mail delivery software. A message that you sent could not be delivered to one or more of its recipients. This is a permanent error. xxx@thalesesec.com Error, ERROR_CODE :554, ERROR_CODE

                                                                                                  • Can't verify domain with AWS Route53

                                                                                                    I have a domain successfully transferred to AWS Route53 from NameCheap. When I try to CNAME or TXT Records as suggested, they are added in AWS console however zohomail does not verify them. For the TXT record zohomail says the value is wrong, whereas

                                                                                                  • Sent emails not going and showing "Processing"

                                                                                                    Hello Team, Could you please assist with sent emails showing "processing" and not actually going through? Many thanks and regards, Cycology

                                                                                                  • LinkedIn verification link and otp not receiving

                                                                                                    For the last 2 to 3 weeks I'm trying to verify my LinkedIn account to access my company's LinkedIn page, Linkedin is sending verification links and codes to this email address but I have not received any codes or links. Please help me here. Looking forward

                                                                                                  • Zoho desk desktop application

                                                                                                    does zoho desk has a destop applicaion?

                                                                                                  • send file to ftp or another external service

                                                                                                    i'v created a zoho creator application for take a picture and rename it by phone. Now i need to send Each renamed pictures to my ftp or to specific folder on google drive...then, delete it from creator. (every picture recived it will processed by another program and stored on my Erp) HOW CAN I DO ??

                                                                                                  • Has anyone built a ticket export that allows Help Center users to export the tickets shown in the My Area list they are looking at?

                                                                                                    Hi, We are moving to Zoho Desk soon. Our current support system displays an option in our help center allowing customers to export their Open, Closed, or all tickets based on which list they are looking at. We need to offer the same in Zoho Desk help

                                                                                                  • Mass pdfs into OCR field

                                                                                                    I am working on a Creator app that my org will use internally. Is there any way to mass upload pfs through a form with an OCR file upload field? Is Creator capable of this, or would I need to use Catalyst?

                                                                                                  • How to upload a file to form file upload field from deluge script.

                                                                                                    Hi guys, I need to store API response into Form File upload field . I'm not getting any errors but PDF file is not assigned to file upload field. You can check possibilities using below details: Method: POST URL: https://v2.convertapi.com/convert/web/to/pdf?Secret=<<SecretKey>>&Token=<<APIKey>>&Url=https://www.google.com You need to generate secretKey and APIKey by Login to https://www.convertapi.com/a/su Response: { "ConversionCost": 4, "Files": { "FileName": "www_google_com.pdf", "FileSize": 68342,

                                                                                                  • Export view via deluge.

                                                                                                    Hi, Is it possible to export a view (as a spreadsheet) via deluge? I would like to be able to export a view as a spreadsheet when a user clicks a button. Thanks     

                                                                                                  • Subform Time field showing as null in script.

                                                                                                    Good Afternoon everyone. I am trying to take the information from my subform and populate it into a multiline field in the CRM. The code below works with no errors. The problem is, it shows that the Open and Close (Time fields) are null. But they are

                                                                                                  • Zoho Payroll's Year in Review 2024

                                                                                                    As we roll into 2025, we'd like to pay tribute to all the milestones we hit in 2024! From releasing out new features that streamlined your workflows to updates that made payroll management smoother, we’ve had a prolific year—all while keeping you, our

                                                                                                  • Is there a way to sort report on record template by a specific field like date field

                                                                                                    Hi, Is it possible to sort the report on the record template by the date field and not the default Added Time. Please check the example bellow: The records are sorting by the added time I wand to change that by the date field,

                                                                                                  • Shared subfolders

                                                                                                    Am I right in thinking that there is no Zoho email application that allows me to create a shared inbox and then add additional folders/subfolders under that inbox? If so, this is really quite incredible and probably a deal breaker for us to start using

                                                                                                  • Update Multi select field values to another form table as individual record

                                                                                                    Hi, I am new to coding and do basics within deluge. I need help with the deluge script to meet the following requirement. Form Student Attendance The fields are : Attendance Date Course (Lookup to Course Form) Class (Lookup to Class Form) Students (Multi

                                                                                                  • Shared Mailbox - Mark as read for all users

                                                                                                    Hi all, Maybe someone can help me out. At the moment we have a shared mailbox without streams. When a users reads an mail or marks it as read other users will not see this. How can we resolve this? We now archive the mails when read and followed up. However

                                                                                                  • Allocate emails to user in a shared mailbox

                                                                                                    Hi, This might be obvious, but I cannot find the answer. I have 3 shared mailboxes so any team member can see the emails. Is there a way of allocating a specific email to a user so that it is their responsibility to deal with it? Thanks in advance.

                                                                                                  • How to view shared mailbox in Outlook

                                                                                                    How to view shared mailbox in Outlook or in another software

                                                                                                  • Search mails in shared mailbox

                                                                                                    Hi everyone, is there a way to search mails in shared mailbox's? Search in streams or mail doesn't return anything from mails in shared mailboxes. Thanks! Rafal

                                                                                                  • Customising the approval email

                                                                                                    Is there anyway to customise the Approval email or to add further fields as the default looks so basic and unlike any of the other email notifications from Desk. My users just thought it was spam.

                                                                                                  • Pushing GCLID info from Gravity Forms to ZohoCRM

                                                                                                    We are switching to Gravity Forms from Zoho Forms and I cannot find any good info on how to make sure my GCLID tracking info is pushed through to the CRM through my new forms. There was an article in the documentation about placing something within the

                                                                                                  • Issue Configuring SSO Integration with Cognito in Zoho Help Center

                                                                                                    Dear Zoho Support Team, We have been working on configuring SSO integration for our Zoho Help Center using Amazon Cognito. While the setup appears to be completed successfully, we are encountering an issue when attempting to access the Help Center. The

                                                                                                  • Need manual aggregate column pathing help

                                                                                                    See linked video here: https://workdrive.zohoexternal.com/external/a5bef0f0889c18a02f722e59399979c604ce0660a1caf50b5fdc61d92166b3e7

                                                                                                  • Merging contacts does fail because of help center membership

                                                                                                    I'm trying to merge two contact records (they are the same contact) where one of them is a member on the help center. The system warns me about this situation and then I de-activate this contact as an "End User" for the help center. Right now the system

                                                                                                  • Duplicate Contacts - how to get merge or delete

                                                                                                    I have noticed that our list of contacts in Zoho Desk duplicates contacts periodically.  I have yet to identify when or why.  How do I merge or delete them?  I see there is a "Deduplicate" but I am unable to find anything that explains this feature.

                                                                                                  • Admin Access to Direct Messages in Zoho Cliq

                                                                                                    Hi Zoho Cliq Team, We would like to request a feature enhancement to enable admin access to one-on-one conversations (direct messages) conducted through Zoho Cliq. Use Case: As administrators, there are situations where it becomes essential to access

                                                                                                  • "Mark as Spam" not working as expected

                                                                                                    Dear support, in the below scenario, clicking on "Mark as spam" identifies only the first of the checked emails as spam, removes that email from the visible list and leaves the rest of the list still visible & unchecked. I've tried check-marking them

                                                                                                  • Massive price increase for user licenses of Zoho Portal

                                                                                                    This actually a complaint about this announcement: https://help.zoho.com/portal/en/community/topic/free-user-licenses-across-all-portal-user-types You present this as an enhancement. And, yes, while reading the main part, I'd agree that (for smaller companies),

                                                                                                  • Elevating Email Security on Zoho Desk: DKIM Now Mandatory

                                                                                                    Hello Zoho Desk Users! It has been a wonderful journey with you on Zoho Desk. As we welcome 2025, we are strengthening our efforts to ensure a secure and seamless experience for you. To enhance email security, DKIM configuration will be mandatory for

                                                                                                  • Calendar - "super compact" week view

                                                                                                    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?

                                                                                                  • Calendar - "pop up" locations

                                                                                                    One of the attractive features of google calendar and outlook calendar is that locations for events will start to automatically populate the location drop down menu as you type. Adding this feature to zoho calendar would be the final feature i need.

                                                                                                  • Next Page