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 Developer Community




                                      Zoho Desk Resources

                                      • Desk Community Learning Series


                                      • Digest


                                      • Functions


                                      • Meetups


                                      • Kbase


                                      • Resources


                                      • Glossary


                                      • Desk Marketplace


                                      • MVP Corner


                                      • Word of the Day



                                          Zoho Marketing Automation


                                                  Manage your brands on social media



                                                        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

                                                                                                  • how do i remove a specific Zoho Service from my account

                                                                                                    I no longer need Zoho CRM, ZRM Assist nor ZRM BugTracker. How do I remove them from the list of apps for my account?
                                                                                                  • Introducing 'Queries' In Zoho CRM

                                                                                                    Hello everyone! We are here with an exciting feature - Queries in Zoho CRM! A little context before we dive right into the feature specifics :) In today’s fast-paced business environment, immediate access to relevant data is essential for informed decision-making.
                                                                                                  • Build custom AI solutions with Catalyst’s QuickML capabilities in CRM

                                                                                                    Hello everyone, We’re thrilled to announce an improvement for our Zoho CRM Enterprise users: the ability to create custom AI solutions using Catalyst’s QuickML directly from Zoho CRM. As you may already know, Zia, Zoho CRM’s AI-powered assistant, offers
                                                                                                  • Unveiling Cadences: Redefining CRM interactions with automated sequential follow-ups

                                                                                                    Last modified on 01/04/2024: Cadences is now available for all Zoho CRM users in all data centres (DCs). Note that it was previously an early access feature, available only upon request, and was also known as Cadences Studio. As of April 1, 2024, it's
                                                                                                  • Pay Contractor Timesheets

                                                                                                    I have contractors that fill out a timesheet. Each hour must be assigned to a current client. I need the easiest way to get the contracts paid. They are paid on an hourly bases. How can this be done?
                                                                                                  • Set up slack alert based on a field changing from one option to any other

                                                                                                    Hi, I'm trying to set-up a workflow to send a slack alert if a field changes from one option to any other. I've set-up a workflow to trigger on Edit and when a specific field gets modified but the only option I have 'is modified to' when really it should
                                                                                                  • Better UI more user friendly

                                                                                                    Hello everyone, I think all finance apps, especially Zoho Books, would benefit from the following suggestions/ notes: 1. Grouping Fields in Zoho Books: Unlike Zoho CRM, Zoho Books does not seem to have an option to create sections or group fields. This
                                                                                                  • Chronicles of 2024: The Year in Retrospect

                                                                                                    As we close out 2024, let’s take a moment to highlight the new features and updates that have enhanced Zoho Invoice in 2024. Among the exciting enhancements, we have launched a new AI-powered chatbot designed to assist you in understanding the app's features
                                                                                                  • Power of Automation :: Automatically archive your inactive Projects

                                                                                                    Hello Everyone, 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
                                                                                                  • 554 5.1.8 Email Outgoing Blocked

                                                                                                    HELP!!!!! My e-mail marymariya@zoho.com is blocked. Error: 554 5.1.8 Email Outgoing Blocked The third day I am writing to the forum, but zohosupport is not responding. Why? What is the problem? I ask to help solve the problem, because I can not communicate with my customer base.
                                                                                                  • Zoho Inventory: Rewinding 2024

                                                                                                  • Custom Modules Now available for Standard and Professional Editions with Expanded Limits across all editions

                                                                                                    #CRM25Q1 Hello Everyone, We are here with an exciting update to Custom Modules in Zoho CRM. Custom modules will now be available to Standard and Professional Edition users, with expanded support across all editions. The standard modules offered in Zoho
                                                                                                  • Assistance with Custom Attendance Report in Zoho People

                                                                                                    Hi, I created a custom report in Zoho People 5.0 to track employee attendance according to our specific needs, as the existing reports do not include all the required details. However, I’ve noticed that the report doesn’t update continuously or on a daily
                                                                                                  • Zoho analyticsでのタブを跨いだ集計

                                                                                                    Zoho analyticsまたはCRMレポートなどを用いて、 見込み客タブと商談タブで共通するユニークキー(リード管理番号)を軸に、「共通選択リスト」で設定した項目別の集計を行うことは可能でしょうか? ・要望 ①リード管理番号をキーに、見込み客テーブルと商談テーブルを結合したRAWデータを作成したい ②具体的には下記表のように「共通選択リスト」項目(サービス)別のマーケ数値を一表にしたい  ※リード=見込み客タブ 商談・成約=商談タブ      リード数 商談数 成約数 サービスA   10   5   2
                                                                                                  • Key Highlights of 2024: Recalling a Year of Progress and Advancements!

                                                                                                    As we step into 2025, we’re excited to share the progress and developments we’ve made to simplify and streamline your travel and expense management in the past year. Let’s take a look back at some of the key updates and enhancements that have helped us
                                                                                                  • How to refresh the page by widget in related list?

                                                                                                    Hello, ZOHO.CRM.UI.Popup.closeReload method does the thing I need. But in my case, I'm not using popup. I have a widget in related list and I want to refresh the page when I'm done with it. I searched for it but I wasn't able to find it. Is there an any
                                                                                                  • your phone line in the uk doesnt work i need help now

                                                                                                    i need to speak with customer service urgently
                                                                                                  • Top Menu Disappeared from Blog Page

                                                                                                    Hi, Our top menu disappeared at Blog Posts page. However, it's still visible any other page on the website. I attached two screenshots, so it can be understood clearly. How can we bring back top menu? Thanks, K.
                                                                                                  • Missing phone numbers

                                                                                                    yesterday I have noticed that most contacts' phone numbers are missing. At first I thought it is a synchronisation problem with my Android phone but as I have found later, numbers are missing on Zoho. I have tried to reimport contacts from a backup but
                                                                                                  • Customise 404 page in Zoho Sites 2.0

                                                                                                    Is it possible to customise the 404 page in Zoho Sites 2? You use to create a new 404 page and that became the default 404 page, but this does not seem to work anymore? Any pointers/suggestions/support appreciated :)
                                                                                                  • [Important announcement] Zoho Writer will mandate DKIM configuration for automation users

                                                                                                    Hi all, Effective Dec. 31, 2024, configuring DKIM for From addresses will be mandatory to send emails via Zoho Writer. DKIM configuration allows recipient email servers to identify your emails as valid and not spam. Emails sent from domains without DKIM
                                                                                                  • 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
                                                                                                  • 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
                                                                                                  • 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
                                                                                                  • 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,
                                                                                                  • Next Page