Bulk Write API in Zoho CRM with PHP SDK: A Comprehensive Guide

Bulk Write API in Zoho CRM with PHP SDK: A Comprehensive Guide

Hi everyone and welcome to another amazing Kaizen week!

This week, we will discuss and explore Bulk Write API in detail, and how to implement the same using Zoho CRM PHP SDK. Please note that the information in the article holds true for Zoho CRM PHP SDK supporting version 5 of Zoho CRM APIs.

What is Bulk Write API?

The Bulk Write API enables you to efficiently insert, update, or upsert a large dataset into your CRM account. As this is an asynchronous API, the records will not be added immediately, instead a job will be scheduled to do so. You will receive a notification at the specified callback URL or you can periodically check the job status.

The Bulk Write API allows you to insert, update, or upsert up to 25,000 records in a single API call. This is much more than the maximum of 100 records that you can insert, update, or upsert using the Insert, Update, and Upsert Records API. 

When to use Bulk Write API?

  • When you want to schedule a job to import a huge volume of data in your CRM account.
  • When you want to insert, update, or upsert more than 100 records in a single API call. 
  • When you want to perform background processes like migration and initial data sync between Zoho CRM and external services.

However, the Bulk Write API consumes 500 credits per job, while the Insert, Update, and Upsert records API consumes 1 credit per 10 records. So, if you only need to insert, update, or upsert a small number of records (5,000 or less), it is economical to use the Records API as it will consume fewer credits.

Here are the major differences between Record APIs and Bulk Write API.

Insert, Update, Upsert Records API
Bulk Write API
You can insert, update, or upsert only up to 100 records per API call.
You can insert, update, or upsert 25000 records per API call.
The response is available instantly.
The response to the Bulk Write API request will not be available immediately. You can check the status of the job by polling for it, or you can wait for the status to be available in the callback URL after the job has completed.
The API consumes 1 credit per 10 records.
Bulk Write API consumes 500 credits per API call. 

Bulk Write API 

To insert, update, or upsert records in bulk, follow the below steps:
  1. Prepare your CSV file
  2. Upload your file in zip format
  3. Create a bulk write job
  4. Check the job status
  5. Download the result

1. Prepare the CSV file

To use the Bulk Write API, you must first create a CSV file containing the data you want to import to Zoho CRM. The first row of the CSV file must contain the field API names, and each subsequent row must contain the data. You can insert, update, or upsert records in a single module using one Bulk Write API call.

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 separated by a semicolon(;) or add a new one.
The pick list value accepts all alphanumeric and special characters.
Ex: Analytics;Bigdata
Date
Accepts date in different formats as mentioned here.
Ex: 2023-05-03
DateTime
Accepts date in different formats as mentioned here.
Ex: 2023-05-03T20:39:19+05:30
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. The accepted formats are mentioned here.
Accepts numeric values.
Ex1: 350
Ex2: 123,344
Currency
Before 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 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.
Please note that comma separated digits are accepted.
Ex1: 250000.90
Ex2: 123,456.657483
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 comma separated numeric values.
Ex1: 250000.50
Ex2: 123,235.345
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 only 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
User
This is a default look-up field for users in Zoho CRM. Accepts the unique ID of the user, which you can get through the get users API.
Ex: User.id

Note:
  • To give multiple values for a multi-select pick list field, enclose them in double quotes("") and separate each value with the semicolon(;).
  • If your multi-line field has more than one line, input them directly by enclosing them in double quotes("").
  • You can only zip one CSV file to upload for bulk write. Adding more than one CSV file into the zip file will result in an error.
  • You can specify a specific format for your number, currency, decimal, date and datetime fields using format key.

Subform Data in Bulk Write API:

The Bulk Write API allows you to import and update records with subforms. To insert or update records with subforms, you must import the parent records first with Bulk Write API, and then the subform records with another Bulk Write API. 

For example, consider an instance where you have a subform named "Contact Details" in the Account module. The subform has the following fields - Contact_Name, Contact_Email and Contact_Phone. You must first create a csv file with the parent records, compress it as a zip file, upload it, and create a bulk write job. 



This is an example csv file. Note the Field API names are in the first row, and the record data is in the subsequent rows.

Once you have imported the parent records, you can upload the subform data CSV. When you prepare the subform data CSV file, it is mandatory to have the parent record ID in the subform data file, along with the subform data. 



This is a sample CSV file for the subform data. The subform data in each row will be added to the corresponding parent record. 

Multiselect Lookup Fields in Bulk Write API

To upload records with multiselect lookup fields, you can follow the same steps as for subforms. First, import the parent records. Then, import the multiselect lookup field data. The CSV file should contain both the parent record ID and the multiselect lookup field data. Please note that this method does not work for line items.

User Lookup in Bulk Write API

To import records with user lookup fields, you can include them in the same CSV file as the parent records. Use the field API name of the user lookup field in the CSV header, and add the unique IDs of the lookup records in the data column for each record.

Once you have prepared the CSV file, compress it as a zip file to upload in the next step. We will add examples of how to add subform data, user lookup and multiselect lookup field data in subsequent sections.

2. Upload your zip file

Once you have your csv file ready and compressed into a zip file, you should upload the same using a POST request. Use the following code snippet to upload the file.


<?php
namespace bulkwrite;

use com\zoho\crm\api\bulkwrite\FileBodyWrapper;
use com\zoho\crm\api\bulkwrite\BulkWriteOperations;
use com\zoho\crm\api\util\StreamWrapper;
use com\zoho\crm\api\bulkwrite\UploadFileHeader;
use com\zoho\crm\api\HeaderMap;

require_once "vendor/autoload.php";

class UploadFile
{
  public static function initialize()
  {
      // Add init code here.
      // Refer to this post for more details
  }

  public static function uploadFile1(string $orgID, string $absoluteFilePath)
  {
    $bulkWriteOperations = new BulkWriteOperations();
    $fileBodyWrapper = new FileBodyWrapper();
    $streamWrapper = new StreamWrapper(null, null, $absoluteFilePath);
    $fileBodyWrapper->setFile($streamWrapper);
    $headerInstance = new HeaderMap();
    //To indicate that this a bulk write operation
    $headerInstance->add(UploadFileHeader::feature(), "bulk-write");
    $headerInstance->add(UploadFileHeader::XCRMORG(), $orgID);
    //Call uploadFile method that takes FileBodyWrapper instance and headerInstance as parameter
    $response = $bulkWriteOperations->uploadFile($fileBodyWrapper, $headerInstance);
    // Add your code to handle the response received in the $response.
  }
}

UploadFile::initialize();
$orgID = "add_your_org_id_here"; // add your zgid which you can obtain using Get Organization API.
$absoluteFilePath = "/Users/test/bulk-write.zip"; //add the absolute file path of your zip file here.
UploadFile::uploadFile1($orgID, $absoluteFilePath);

The uploadFile() method takes two parameters: the organization ID ($orgID) and the absolute file path ($absoluteFilePath) of the file to be uploaded. Within the uploadFile() method, an instance of BulkWriteOperations is created to call the Bulk Write API.  This API is used to upload files to the Zoho File System. The HeaderMap instance is created to hold the necessary headers for the API request. The UploadFileHeader::feature() and UploadFileHeader::XCRMORG() methods are used to set the feature and organization ID headers, respectively. These headers are required to identify the type of operation being performed and the organization that the file is being uploaded.
 The uploadFile() method is called on the BulkWriteOperations instance, passing the FileBodyWrapper and HeaderMap as parameters. The response from the API call will be stored in the $response variable, which contains the file ID as well. We will use this file ID in the next step, creating a bulk write job.

We hope you found this post on the Bulk Write API useful. In next week's post, we will cover how to create a bulk write job, including lookup and user lookup fields and subform data. We will also show you how to check the job status and download the job result.

If you have any specific questions about the Bulk Write API, please leave a comment below,  or reach out to us at support@zohocrm.com. We are happy to help!

Thank you for reading! Stay tuned for more useful posts in the series. See you all next week!

    Access your files securely from anywhere


            Zoho Developer Community





                                      • Desk Community Learning Series


                                      • Digest


                                      • Functions


                                      • Meetups


                                      • Kbase


                                      • Resources


                                      • Glossary


                                      • Desk Marketplace


                                      • MVP Corner


                                      • Word of the Day


                                      • Ask the Experts



                                          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

                                                                                                  • CPQ Quantity suggestion does not allow multiple products

                                                                                                    I have come across an issue in the CPQ Product Configuration. I want 10 products to trigger the suggestion of an additional product via the quantity in quoted items function. However, when specifying the configuration, I am only able to choose one base
                                                                                                  • BUG ALERT: Client Script + Commands -> $Page contextual data is not updated

                                                                                                    When using the new Client Script Commands feature, there is an issue with the Client Script $Page contextual data not accurately being updated each time a Command is run. Assuming a Client Script Command called "Client Script Command Bug" with the following
                                                                                                  • Accepted meeting invites not showing on calendar

                                                                                                    I can receive a calendar invite to a meeting, I confirm I can attend and hit accept. I then check my calendar and it doesn't show. 30 seconds later, it does show up but it is delayed leaving the feeling something didn't work correctly. Can this be improved,
                                                                                                  • Access Tokens and Webhooks

                                                                                                    I have a linux server application that I want to be able to talk to the cliq chatbot and get a response back to that linux server application. This is for the linux server application to check the chat/channel's message history in Cliq. The Zoho API console
                                                                                                  • info, hr, support, ... etc.

                                                                                                    Hello, I want to have a dedicated inbox email as info@mydomain.com, hr@mydomain.com, support@mydomain.com ... etc. , and be able to use these email inboxes inside Zoho applications like using the info with my CRM Email configuration, the email used for
                                                                                                  • How to add curly quotation marks and apostrophes in Zoho Mail

                                                                                                    Is there a way to set up Zoho Mail so that, when I compose email messages, my quotation marks and apostrophes are curly rather than straight? I read a couple of 12-year-old conversations about this topic but specific to Zoho Writer and there was no
                                                                                                  • Import Woocommerce Orders to Zoho Books with Zoho Flow

                                                                                                    Hi folks, is it possible to import Woocommerce orders to Zoho Books using Zoho flow? Usually the Woocommerce Orders have several line which would need to be imported. When I click on "use this flow" it will have me sign in, which is fine, and then I am
                                                                                                  • Zoho task approaching due date notification on Cliq.

                                                                                                    Hello, Currently is possible to set reminders on each task to send an email to the task owner on x days before the due date. I'd like to propose a configuration that you can set in a way that sends cliq messages to the task owner when the due date of an task is approaching (like 3, 5, 7 days before, it's supposed to be configurable). Would be nice to have this kind of notification. I've integrated my Projects with Cliq Extension and it does not have this function (as far as I know) Does somebody
                                                                                                  • How to restrict on duty Requests?

                                                                                                    We need to restrict on duty requests for our employees, for example Work from Home limited to max 16 hours per week, or client visit limited to max 2 days per week How can we do that?
                                                                                                  • Change default "Sort by"

                                                                                                    Is there a way to change the default "sort by" when searching across modules?" in Zoho CRM? Currently the default sort method is "Modified time" but i would like to utilize the second option of "relevance" as the sort by default and not have to change
                                                                                                  • Marking a Desk ticket as Unread after merge

                                                                                                    We have a custom script that runs against every new ticket and auto-merges it with any existing ticket that matches our criteria. That works fine but there is no functionality that reverts the newly-updated ticket back to an "unread" state. I found the
                                                                                                  • Addition of RE: to Every Reply Email

                                                                                                    Hi, In Zoho mail every time I reply to an email it puts a RE: in the subject line. So after a few replies on same email the subject line looks like RE: RE: RE: RE:RE: RE: RE: Order Details Can I stop Zoho mail from doing this bug? Thanks, Grant
                                                                                                  • Operation not permitted

                                                                                                    I'm trying to set up email for this site - pawsathome.uk - and when I go to: Admin Console>Domains>Add> I keep getting error - 'Operation not permitted' - See attachment. WHY??
                                                                                                  • User Filter for Dynamic Date Dimensions in Zoho Analytics

                                                                                                    One challenge I frequently encounter is the need to create multiple versions of the same report—one for yearly data, another for quarterly data, another for monthly, and so on. While this works, it leads to unnecessary duplication, making maintenance
                                                                                                  • In this zoho email option ₹700 /user /year what is the storage space provided?

                                                                                                    In this zoho email option ₹700 /user /year what is the storage space provided?
                                                                                                  • Making another calendar your default calendar

                                                                                                    I am trying to make another calendar my default calendar when I add events to it. It keep going to a single calendar, I need it to go to my google calendar by default, as this is linked to other services / websites. I cannot find an option to make it
                                                                                                  • Zoho Mail Setup for New Domain ModZbig.com

                                                                                                    Respected Zoho Support Community, I have this account as my personal account, I bought a new domain https://modzbig.com/ and I need to know can I setup free Email Setup with this account for my new domain. My new website is about to provide latest mod
                                                                                                  • Displaying Inactive Customers & Vendors

                                                                                                    Can we please have this choice in general settings, it's a pain showing hundreds of inactive records. A simple search clears the "Active records" filter ! A simple message showing "Inactive records match your search criteria but have been omitted, would
                                                                                                  • Consigo excluir um e-mail que enviei errado?

                                                                                                    Olá, enviei um email para um cliente e escrevi coisas erradas, como posso excluir este email enviado da caixa do cliente? existe essa possibilidade de cancelar e-mails que foram enviados? Obrigada
                                                                                                  • Unable to send message;Reason:553

                                                                                                    Can Receive email, but Not sending. Please check & let me know the possible solution.  zb14340497 Thanks
                                                                                                  • Font Size 11 - Zoho CRM Email Templates

                                                                                                    Our company communicates with our vendors exclusively using Calibri Font Size 11, as this is the standard formatting for professional emails. Since the CRM only allows for the selection of font sizes 10 & 12, we have been unable to utilize the CRM email
                                                                                                  • Adding Attachment to Desk Ticket via Deluge

                                                                                                    Hello, My team has a process where some people are entering information into a workbook in Zoho Sheet, and we need to get a copy of workbook into a ticket in Desk. We currently have a 'Submit' button on the Sheet that triggers a webhook to Flow, and from
                                                                                                  • Set Custom Icon for Custom Modules in new Zoho CRM UI

                                                                                                  • Power-up your app with spreadsheet editing using Zoho Office Integrator!

                                                                                                    Hello users, Did you know that you can create and edit spreadsheets right in your web app? With Zoho Office Integrator's embeddable spreadsheet editors, you can easily add the capability to create and edit spreadsheets collaboratively in your app. With
                                                                                                  • Lead Blueprint transition in custom list view

                                                                                                    Hi, Is It possible to insert the Blueprint transition label in a custom Canvas list view? I am using Lead module. I see the status, but it would be great if our users could execute the Blueprint right from the list view without having to enter the detailed
                                                                                                  • Time Based Workflow Rules for Projects and Tasks

                                                                                                    Project managers spend a significant amount of time manually monitoring task deadlines, notifications, and follow ups. Zoho projects' Workflow Rules help automate these repetitive processes and save valuable time. Workflow rules are a set of actions that
                                                                                                  • How to Send Weekly Scheduled Emails of a Custom View

                                                                                                    Greetings, We have a custom view called "All Employee View" for the Employee form. We are able to manually export that view using the "Export" button: However, we want to programmatically export this view as an XLS file each week and send it in an email
                                                                                                  • Extract first and last name

                                                                                                    I am trying to build a custom function in Flow, when a new Zoho Booking is added I want to split the Name field into first last name. I understand the function needs to be a string and this works but I am unsure how to write this in the flow script. result
                                                                                                  • Field value permission to set for automation to work as expected?

                                                                                                    I would like confirmation on the CRM software behaviour with the following configuration. A while ago I had discovered the solution by trial-and-error and now I don't remember what the conclusion was. I have a picklist field in the layout that I only
                                                                                                  • SEO for your Zoho Sites Website

                                                                                                    Join our live webinar to learn how to use Zoho Sites' SEO tools to boost your website's ranking. Our product specialist will demonstrate everything you need to know about optimizing your web pages to make them search engine friendly. Register here for free: https://www.zoho.com/sites/webinars/
                                                                                                  • Convert Leads to Deals in Portals?

                                                                                                    Is there a way to convert leads to deals, like the main program does? It doesn't seem to do it in portals. It seems a bit pointless having it.
                                                                                                  • Default view in Email on Company Module

                                                                                                    Is there a way to default the view on the COMPANY module to be "Emails Associated with the Related Contact" it is extremely frustrating to have to swap it every time. This is fairly new - it used to have it defaulted differently
                                                                                                  • Custom module in Portals won't edit

                                                                                                    I have a custom module but Portals access users can't edit it. They can create and delete though. In the Portals settings I have Create, Edit and Delete set turned on. Anyone know what this could be?
                                                                                                  • Kaizen #111 : Set default values based on Page Layouts using Client Script

                                                                                                    Hello everyone! Welcome back to another interesting Kaizen post. In this post, let us discuss how to set default values for fields based on different layouts using Client Script. In this Kaizen post, What are Page Layouts? Client Script is specific for
                                                                                                  • YET ANOTHER BUG: Client Script Flyouts no longer acting like Flyouts

                                                                                                    As per https://help.zoho.com/portal/en/community/topic/kaizen-157-flyouts-in-client-script one of the key benefits of a Flyout over a Popup is the ability to move it around the page. This no longer works. The "width" and "height" configuration settings
                                                                                                  • Does Client Script work on Zoho CRM Portal?

                                                                                                    Hi ! I create a new module to use at customer portal. But Client Script looks not work. Please help me clarify, thank you!
                                                                                                  • Translation in Zoho CRM now supports various regional languages

                                                                                                    Release status (Last modified on January 2, 2025): This feature is currently available for all users in enterprise and above editions, across all data centers. Hello everyone, Imagine a multinational company with teams spread across various regions, each
                                                                                                  • Drop down of Zoho users aka Employees

                                                                                                    Is there any field I can add to have an up-to-date list of current Zoho users ? Use case is for an employee to select their manager - however I don't want to have to manually populate a dropdown field every time someone joins or leaves our company. Why
                                                                                                  • Add multiple users to a task

                                                                                                    When I´m assigning a task it is almost always related to more than one person. Practical situation: When a client request some improvement the related department opens the task with the situation and people related to it as the client itself, the salesman
                                                                                                  • Last Name / First Name

                                                                                                    Hello , My company adds contacts on a "Last Name , First Name" basis. We've noticed that when viewing accounts there is no " , " (comma). It's VERY misleading. I have set the custom view to show "last name" "first name" instead it joins them both and
                                                                                                  • Next Page