Kaizen #104 - Bulk Write API using PHP SDK (v5) - Part II
Welcome to another exciting week of Kaizen! This week, we will continue our discussion on Bulk Write API. In last week's post, we covered the features of Bulk Write API, and explained in detail the first two steps involved in using Bulk Write API. Today, we'll discuss how to create a bulk write job, fetch the job status, and download the results.
1. Prepare the CSV file
2. Upload your zip file
3. Create a Bulk Write job
After uploading the file and obtaining the file ID, the next step is to create a bulk write job. For this, you will require the file ID, callback URL, and the field API names to perform one of the three operations: insert, update, or upsert. Upon a successful API call, the response will provide a job ID, with which you can check the job status in the next step.
The following are the keys you need to set.
- callback (JSON object, optional) : The CallBack object defines the callback URL and method for receiving notifications or updates about the job's status.
- character_encoding (string, optional) : Specify the encoding to be used for the data being written.
- operation (string, mandatory) : Specify the type of operation to be performed in the bulk write job. Possible values are insert, update and upsert.
- 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.
- resource (JSON array, optional): Initiate an object of Resource class that contains the details of the module, file, and field mappings associated with the bulk write job. The resource array contains the file_id, module, find_by, field_mappings and type keys. For more details, refer to our help document here.
Mapping fields in bulk write jobs
To specify which value in the CSV file should be mapped to which field in the CRM module, you can use the field_mappings key in the resource array. This is an optional key, and if you omit it, the system will use the headers of the CSV file to map the fields. When the field_mappings is skipped, the CSV headers must be the field API names and, all the columns of your CSV file will be used for import. In this case, you should remove columns that you do not want to import into your CRM account.
Please note that the CSV headers will be ignored if field_mappings is used while creating the bulk write job.
When to use the field_mappings key?
You should use the field_mappings key if:
- The column headers in your CSV file are different from the field API names in the CRM module.
- You want to ignore certain columns in the CSV file.
- You want to specify a default value for a field in the CRM module.
Rules for using the field_mappings key
- When you map a field by specifying the field_mappings key, it is mandatory to specify either the index or the default_value key, or the system will throw an error.
- The index is the position of the field in the CSV file, starting from 0.
- The default_value key is used when you want to provide a default value for a field. By specifying a default value, you ensure that if a cell in the CSV file is empty, the system will populate it with the default value.
- Use the ignore_empty key when you want the system to skip updating fields that are empty in the source file. Please note that for insert operation, ignore_empty will be set as false by default.
Index | Default Value | Ignore Empty | Empty Cell | Action |
YES | YES/NO | TRUE/FALSE | NO | CSV Value |
YES | YES | TRUE/FALSE | YES | Default Value |
YES | NO | TRUE | YES | No Update |
YES | NO | FALSE | YES | Empty |
| NO | YES | TRUE/FALSE | YES/NO | Default Value |
- If you specify the index and there are no empty cells in the source file, the system will use the values from the CSV file for the corresponding fields. The default_value will be ignored in this case.
- For update and insert operations, when the index is specified and there are a few cells for which the value is empty in the source file, then for the corresponding records with empty value:
- If default_value is specified, the field will be updated with the default_value.
- If default_value is not specified, the system will handle the corresponding fields differently depending on the value of the ignore_empty key.
- The field will be left untouched if ignore_empty is set to TRUE.
- The field will be updated to an empty value if ignore_empty is FALSE.
- When the index is not specified, but a default_value is given, the system will update the corresponding fields in the CRM module with the specified default value.
Bulk Insert with lookup and user lookup data
Here is an example of a simple bulk write job request:
<?php namespace bulkwrite; use com\zoho\crm\api\bulkwrite\BulkWriteOperations; use com\zoho\crm\api\bulkwrite\RequestWrapper; use com\zoho\crm\api\bulkwrite\CallBack; use com\zoho\crm\api\util\Choice; use com\zoho\crm\api\bulkwrite\Resource; use com\zoho\crm\api\bulkwrite\FieldMapping; use com\zoho\crm\api\modules\MinifiedModule; use com\zoho\crm\api\bulkwrite\DefaultValue; require_once "vendor/autoload.php"; class CreateBulkWriteJob { public static function initialize() { // Add init code here. // Refer to this post for more details } public static function createBulkWriteJob(string $moduleAPIName, string $fileId) { $bulkWriteOperations = new BulkWriteOperations(); $requestWrapper = new RequestWrapper(); // Set the callback URL, and method $callback = new CallBack(); $callback->setUrl("add_your_callback_url_here"); $callback->setMethod(new Choice("post")); $requestWrapper->setCallback($callback); $requestWrapper->setCharacterEncoding("UTF-8"); //character encoding $requestWrapper->setOperation(new Choice("insert")); //specify the type of operation // module, file and field mapping details $resourceIns = new Resource(); // To set the type of module that you want to import. The value is data. $resourceIns->setType(new Choice("data")); $module = new MinifiedModule(); $module->setAPIName($moduleAPIName); $resourceIns->setModule($module); $resourceIns->setFileId($fileId); $resourceIns->setIgnoreEmpty(true); $fieldMapping1 = new FieldMapping(); $fieldMapping1->setAPIName("Account_Name"); $fieldMapping1->setIndex(0); $fieldMapping2 = new FieldMapping(); $fieldMapping2->setAPIName("Phone"); $fieldMapping2->setIndex(1); $fieldMapping3 = new FieldMapping(); $fieldMapping3->setAPIName("Parent_Account"); $fieldMapping3->setIndex(2); $fieldMapping3->setFindBy("id"); $fieldMapping4 = new FieldMapping(); $fieldMapping4->setAPIName("Referred_User"); $fieldMapping4->setIndex(3); $fieldMapping4->setFindBy("id"); $defaultValue = new DefaultValue(); $defaultValue->setValue("4876876327565"); $fieldMapping4->setDefaultValue($defaultValue); $resourceIns->setFieldMappings([$fieldMapping1, $fieldMapping2, $fieldMapping3, $fieldMapping4]); $requestWrapper->setResource([$resourceIns]); //Call createBulkWriteJob method that takes RequestWrapper instance as parameter $response = $bulkWriteOperations->createBulkWriteJob($requestWrapper); // Add your code to handle the response received in the $response. } } CreateBulkWriteJob::initialize(); $moduleAPIName = "Accounts"; //The module to which you want to insert the records $fileId = "48768764054001"; // add your file_id received in the response of Upload File CreateBulkWriteJob::createBulkWriteJob($moduleAPIName, $fileId); |
In the above code, Referred_User is a user lookup field, and Parent_Account is a lookup field in the Accounts module. The CSV file contains the unique ID of the corresponding records in the lookup modules.
Here is a sample CSV file used for the above Bulk Insert job. Note that the unique record IDs of the lookup (Parent_Account) and user lookup(Referred_User ) fields. If you choose to schedule the job without using field mappings, ensure that you provide headers for these fields in the format field_api_name.id with the record IDs in the corresponding columns.
Updating or Upserting records by unique key:
During an update operation, the find_by field acts as a unique key that identifies the record to be updated. You can use the unique record id, or any other unique field for this. For example, if the Phone field is a unique field in the Accounts module, specifying setFindBy("Phone") allows updates based on the values present in the Phone field. Similarly, for an upsert operation, if there is no existing record matching the provided Phone number, a new record will be inserted. Conversely, if a matching record is found, it will be updated.
Here is the code snippet for the field_mapping for an update operation using the Phone field as the unique key.
//You can use setFindBy method to update/upsert records based on a unique field $resourceIns->setFindBy("Phone"); //fieldMapping for the unique field $fieldMapping1 = new FieldMapping(); $fieldMapping1->setAPIName("Phone"); $fieldMapping1->setIndex(1); $fieldMapping2 = new FieldMapping(); $fieldMapping2->setAPIName("Description"); $fieldMapping2->setIndex(8); |
Importing Subform Data
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. For this bulk write job, $moduleAPIName has to be set with parent module with proper $fieldMapping. Refer to the first sample for more details.
Once you have imported the parent records, get the parent record ids, prepare the CSV file with the subform data, and create a Bulk Write job for the subform module. You can get the parent record ids from the result zip file in Step 5 (Download the result). Refer to our previous post to know how to prepare the CSV file with the Subform data.
Consider a subform named Contact_details in the Accounts module, with the fields Contact_Name, Contact_Email, and Contact_Phone. Here is the code snippet for the field_mapping to import the subform data.
//field_mapping for the Parent_Id $fieldMapping1 = new FieldMapping(); $fieldMapping1->setAPIName("Parent_Id"); $fieldMapping1->setIndex(0); $fieldMapping1->setFindBy("id"); //add proper field_mapping for the subform fields with the subform field API names |
Note that in this case, the $moduleAPIName is the api name of the subform (Contact_details) and the operation type should be insert. The subform data is added to the corresponding record specified by Parent_Id field in the subform CSV.
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 using a Bulk Write job. Then, import the multiselect lookup field data using another Bulk Write job. For 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.
Consider a multiselect lookup field named Clients in the Accounts module, which is linked to the Contacts module. In your CSV file, ensure that you include both the Parent Record ID and the linked record IDs. For multiselect lookup data, the $moduleAPIName should be the API name of the linked module, and in the field_mappings, the API names used should correspond to the field API names from the lookup module. Check the following sample code for more details.
//field_mapping for module 1 (Contacts) $fieldMapping1 = new FieldMapping(); $fieldMapping1->setAPIName("Client_Account"); //field API name in the linked module $fieldMapping1->setIndex(0); $fieldMapping1->setFindBy("id"); // field_mapping for module 2 (Accounts) $fieldMapping2 = new FieldMapping(); $fieldMapping2->setAPIName("Account"); // field API name in the linked module $fieldMapping2->setIndex(1); $fieldMapping2->setFindBy("id"); |
4. Check job status
The Bulk Write API offers two options for monitoring the status of a job: polling and callback. If you prefer not to poll for job status, you can wait for the system to notify you of job completion by using the provided callback URL in the Create Bulk Write Job request. Alternatively, you can choose to poll the API using the job ID obtained from the previous step to check the status of the scheduled bulk write job. The job status can be one of the following: ADDED, INPROGRESS, or COMPLETED. Only completed jobs will include the download-URL key in the response.
Here is a code snippet to check the job status and get the download URL from the response.
public static function getBulkWriteJobDetails(string $jobId) { $bulkWriteOperations = new BulkWriteOperations(); //Call getBulkWriteJobDetails method that takes jobId as parameter $response = $bulkWriteOperations->getBulkWriteJobDetails($jobId); if ($response != null) { $responseWrapper = $response->getObject(); if ($responseWrapper instanceof BulkWriteResponse) { $result = $responseWrapper->getResult(); if ($result != null) echo ("Bulkwrite DownloadUrl: " . $result->getDownloadUrl() . "\n"); } } } |
5. Download the result
In this step, you can obtain the result of the bulk write job in a ZIP file that includes a CSV file containing the details of the job. Please note that you can get the details of only one bulk write job in a single API call.
To download the result, you need to use the download_url provided in the response. The CSV file will consist of the first three mapped columns from the uploaded file, as well as three additional columns: STATUS, RECORD_ID, and ERRORS.
{ public static function initialize() { // Add init code here. // Refer to this post for more details } public static function downloadBulkWriteResult(string $downloadUrl, string $destinationFolder) { $bulkWriteOperations = new BulkWriteOperations(); $response = $bulkWriteOperations->downloadBulkWriteResult($downloadUrl); // Add your code to handle the response received in the $response. } } DownloadBulkWriteResult::initialize(); $downloadUrl = "paste_your_download_url_here"; $destinationFolder = "/Documents"; DownloadBulkWriteResult::downloadBulkWriteResult( $downloadUrl,$destinationFolder); |
The image shows the result of an Upsert operation. As you can see, few of the records were skipped because the unique field had a duplicate value.
We hope you found this post useful. If you have any further questions, reach out to us at support@zohocrm.com or let us know in the comments section. We are looking forward to hearing from you!
Stay tuned for more useful posts in the series. See you all next week!
Access your files securely from anywhere
New to Zoho Recruit?
Zoho Developer Community
New to Zoho LandingPage?
Zoho LandingPage Resources
New to Zoho Survey?
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho CRM Plus?
Deliver unforgettable customer experiences
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Zoho Marketing Plus?
Everything you need to run your marketing
New to Bigin?
Topic Participants
Anu Abraham
Sticky Posts
Kaizen #217 - Actions APIs : Tasks
Welcome to another week of Kaizen! In last week's post we discussed Email Notifications APIs which act as the link between your Workflow automations and you. We have discussed how Zylker Cloud Services uses Email Notifications API in their custom dashboard.Kaizen #216 - Actions APIs : Email Notifications
Welcome to another week of Kaizen! For the last three weeks, we have been discussing Zylker's workflows. We successfully updated a dormant workflow, built a new one from the ground up and more. But our work is not finished—these automated processes areKaizen #152 - Client Script Support for the new Canvas Record Forms
Hello everyone! Have you ever wanted to trigger actions on click of a canvas button, icon, or text mandatory forms in Create/Edit and Clone Pages? Have you ever wanted to control how elements behave on the new Canvas Record Forms? This can be achievedKaizen #142: How to Navigate to Another Page in Zoho CRM using Client Script
Hello everyone! Welcome back to another exciting Kaizen post. In this post, let us see how you can you navigate to different Pages using Client Script. In this Kaizen post, Need to Navigate to different Pages Client Script ZDKs related to navigation A.Kaizen #210 - Answering your Questions | Event Management System using ZDK CLI
Hello Everyone, Welcome back to yet another post in the Kaizen Series! As you already may know, for the Kaizen #200 milestone, we asked for your feedback and many of you suggested topics for us to discuss. We have been writing on these topics over the
New to Zoho TeamInbox?
Zoho TeamInbox 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
Design. Discuss. Deliver.
Zoho Show Resources
Get Started. Write Away!
Writer is a powerful online word processor, designed for collaborative work.
Zoho CRM コンテンツ
-
オンラインヘルプ
-
Webセミナー
-
機能活用動画
-
よくある質問
-
Ebook
-
-
Zoho Campaigns
- Zoho サービスのWebセミナー
その他のサービス コンテンツ
Nederlandse Hulpbronnen
ご検討中の方
Recent Topics
Live webinar: Explore WorkDrive's seamless integrations with key Zoho apps
Hello everyone, We’re excited to invite you to our upcoming live webinar, where we'll delve into the seamless integration of WorkDrive with other key Zoho applications! This is a fantastic opportunity to enhance your productivity and streamline your workflowsLive webinar: Getting the most out of WorkDrive in Zoho Workplace
Hello everyone, We’re excited to invite you to our upcoming live webinar, where we’ll explore how to maximize your use of WorkDrive as part of the Zoho Workplace bundle. This is a fantastic opportunity to elevate your productivity and streamline yourLive webinar: Mastering data migration, organization, and team collaboration
Hello everyone, We’re excited to invite you to our upcoming live webinar! Discover how to seamlessly migrate your data, optimize file organization, and boost team collaboration using Zoho WorkDrive’s powerful features. This is a fantastic opportunityJoin our live webinar: Explore the WorkDrive TrueSync application!
Hello everyone, We are thrilled to invite you to a live webinar focused on mastering the WorkDrive TrueSync application. Discover how to seamlessly sync your content between the cloud and your computer, ensuring smooth and efficient file management. OurZoho Creator customer portal limitation | Zoho One
I'm asking you all for any feedback as to the logic or reasoning behind drastically limiting portal users when Zoho already meters based on number of records. I'm a single-seat, Zoho One Enterprise license holder. If my portal users are going to add records, wouldn't that increase revenue for Zoho as that is how Creator is monetized? Why limit my customer portal to only THREE external users when more users would equate to more records being entered into the database?!? (See help ticket reply below.)Script Editor not an option
I am trying to apply a script to a sheet and Script Editor is not an option. I don't want to go outside Sheets to do this (like Creator) if it can be done inside Sheets.Envio de mails
Hola! No puedo enviar mails pero si recibirlos. No se como solucionarlo! Mi dominio es chidobebes.com.arERROR CODE :554 - Your access to this mail system has been rejected due to poor reputation of a domain used in message transfer
In my email configuration: The domain's MX Records are pointed to Zoho The domain's SPF Records have been pointed out successfully DKIM is enabled. DMARC Record is pointed for the domain. The domain name is digioorja.in. Still facing the issue of Error:This Operation has been restricted. Please contact support-as@zohocorp.com for further details
l tried to verify my domain (casalimpaeperfumada.com.br) and its shows this error: This Operation has been restricted. Please contact support-as@zohocorp.com for further details.SLOW EMAILS
Is there an issue with the Zoho server? For two days now I've been having issues with very long buffering. Please advise. Thank you.POP3 authentication error - SOLVED
Just in case others are as forgetful as me ... As Zoho has changed the POP server for personal and free organisational users, I needed to change the POP server on my email client. This failed persistently but eventually I remembered that I had chosenSolution to Import PST File into Office 365.
MailsDaddy OST to Office 365 Migration Tool is an outstanding solution to recover OST files and migrate them into Office 365 without any hassle. Using this software users can multiple OST files into Office 365 with complete data security. It offers usersAdd Zoho One Groups/Departments to Shared Mailbox Access
Hi, I hope you're doing well. Currently, in Zoho Mail, I can manually add specific users or the entire organization to a shared mailbox. However, there is no option to add Zoho One groups or departments. Feature Request: We would like the ability to assignAllow Filters with Only Special Characters in Zoho Mail
Hi Zoho Mail Team, I hope you're doing well. We have noticed that currently, Zoho Mail does not allow creating filter criteria using only special characters, such as = or #. However, there are scenarios where such a filter is necessary. For example: FilteringHow to save email as PDF?
I saw 2 previous threads about this. One is from 14 years ago. The other was closed as "answered" a year ago but the feature was never implemented: https://help.zoho.com/portal/en/community/topic/how-to-download-save-emails-as-pdf Is the "save as PDF"Flexible plans
Hi, I have a Workplace Standard subscription. On Zoho's website, it mentions that with the annual plan it's possible to have multiple plans under the same organization—for example, Workplace Standard and Mail Lite. However, I can’t find a way to do thisWeekly Tips : Teamwork made easy with Multiple Assignees
Let's say you are working on a big project where different parts of a single task need attention from several people at the same time—like reviewing a proposal that requires input from sales, legal, and finance teams. Instead of sending separate remindersCannot give public access to Html Snippet in Zoho Creator Page
Hi, I created a form in Zoho Creator and published it. The permalink works but I want to override the css of the form. (style based URL parameters is not good enough) So I created a page and added an Html snippet. I can now override the css, which isWeekly Tips : Customize your Compose for a smoother workflow
You are someone who sends a lot of emails, but half the sections in the composer just get in your way — like fields you never use or sections that clutter the space. You find yourself always hunting for the same few formatting tools, and the layout justAccounting on the Go Series-43:Enhancing Your Reporting Efficiency with Dashboard Filter State Retention
Hello everyone! Welcome back to our series on Zoho Books mobile app features. Today, we will talk about a feature that yet again helps you focus on work that really matters-Dashboard Filter State Retention. Imagine you're working on your Zoho Books dashboard,Zoho books/payroll tax payment
I accidentally made a second payment to my taxes for $300 which is reflected in my bank account and therefore on Zoho books but I can not match it to any transactions because its not reflected in payroll as a tax payment. Is there a way to add an extraI can't renew the Finance Plus subscription
I tried to renew the Finance Plus subscription but it keeps reloading the same page over and over when ever I click on "Renew Subscription" buttonEstimate vs Quote
they are different. Quote is for 1 piece price + other charges. Estimate is for total quantity to be ordered. The gross total amount of the Estimate is the amount payable. Replacing Estimate as Quote is not understandable because they are different. InAccounting on the Go Series-47: Effortless GSTIN Management- Auto Populate TaxPayer Details in Zoho Books Mobile App
Hello everyone, Welcome back! Today, we're focusing on a feature specifically designed for our Indian users in the Zoho Books-Indian edition, particularly those who deal with GST compliance regularly. We understand the importance of accurate and efficientAccounting on the Go Series-48: Enhance Accuracy with Custom Work Week Start Days in Zoho Books iOS app
Hello everyone, Welcome back! We’re here with another feature spotlight that might seem small but can have a big impact on your daily routine: setting the first day of the work week in the Zoho Books iOS app. Imagine this: You’re a business owner whoTime to Get Paid Report in ZBooks
Hello, One of our customers who has 25 different companies around the world gets 60 days to make payments. Unfortunately, the subject report does not report an average time to get paid (in days) or the ability to look at a custom period of time. CurrentlyHow to prepare a balance sheet for a company that has no operations yet?
.Project Billing Method from Zoho People
Normaly our customers use Zoho Projects to manage projects and timesheet that are being charge to the customer. Using the integration from Zoho Project we can have projects base on different billing method. For example most of our customer use HourlyZoho Books-Accounting on the Go Series!
Dear users, Continuing in the spirit of our 'Function Fridays' series, where we've been sharing custom function scripts to automate your back office operations, we're thrilled to introduce our latest initiative – the 'Zoho Books-Accounting on the Go Series'.Zoho Books | Product updates | July 2025
Hello users, We’ve rolled out new features and enhancements in Zoho Books. From plan-based trials to the option to mark PDF templates as inactive, explore the updates designed to enhance your bookkeeping experience. Introducing Plan Based Trials in ZohoZoho Books | Product updates | August 2025
Hello users, We’ve rolled out new features and enhancements in Zoho Books. From the right sidebar where you can manage all your widgets, to integrating Zoho Payments feeds in Zoho Books, explore the updates designed to enhance your bookkeeping experience.Update or Upsert Records Using Unique Custom Fields
Hello customers, We've enhanced the process of updating records via API. You can now: Update records using unique custom fields Upsert records using unique custom fields Note: Both the features are available in the Zoho Books and Zoho Inventory apps.[Webinar] Understanding the New Invoice Management Systems
Join industry expert CA Pritam Mahure as he discusses the importance of the new Invoice Management System (IMS) and its impact on taxpayers. Topics Covered: - Concept of IMS and pre-requisites - Applicability and Restrictions on Invoices/Records for IMSAccounting on the Go Series-51: Effortless Transactions: Create and Manage Directly from Uploaded Documents
Hello everyone, We’re back with another useful feature that makes working with Zoho Books even easier! This time, we’re simplifying the process of creating transactions directly from uploaded documents. Imagine you’re out meeting clients, and you receive[WEBINAR] Effortless migration to the VAT-ready South Africa edition of Zoho Books
Hello there, If you are one of our early users from South Africa using the older edition of Zoho Books, this webinar is for you! We have now launched a new South Africa edition with VAT support, to which you can migrate your existing data. Join this session,Accounting on the Go Series-52: Capture Receipts on the Go, Right from Your Lock Screen.
Hello everyone, We’re excited to introduce a feature that will make your life so much easier—especially for those constantly on the move! With iOS 18, Zoho Books now allows you to capture receipts directly from your lock screen using Locked Camera Capture.AT - Austrian Accountant familiar with ZOHO
Hello, as I have just migrated to ZOHO and unfortunately have to change my accountant next year, I am looking for an accountant (for Austria) who already has experience with Zoho or who already manages clients using Zoho books. Is there anyone here fromZoho Workflow issue
Dear Zoho Users, I have Zoho Books premium subscription, I have created a email alerts workflow for Invoices and following are the configurations for the same: 1. Workflow for Invoice module 2. Choose when to tigger - created or edited 3. Filter the triggersAccounting on the Go Series-53: Swift Transactions at Your Fingertips-Zoho Books in Your Control Center
Hello again, We’ve all had those moments where you need to get something done quickly, but the process of unlocking your phone, finding the app, and navigating through menus slows you down. Now, with Zoho Books integrated into the iOS 18 Control Center,Update on PDF Download Issues Caused by Antivirus Software
Hello users, Antivirus software is designed to protect your computer from malicious software and threats. However, they may mistakenly identify legitimate files and software as threats at times. This is known as a false positive. We have received reportsNext Page