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
Centralize Knowledge. Transform Learning.
All-in-one knowledge management and training platform for your employees and customers.
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 #198: Using Client Script for Custom Validation in Blueprint
Nearing 200th Kaizen Post – 1 More to the Big Two-Oh-Oh! Do you have any questions, suggestions, or topics you would like us to cover in future posts? Your insights and suggestions help us shape future content and make this series better for everyone.Kaizen #226: Using ZRC in Client Script
Hello everyone! Welcome to another week of Kaizen. In today's post, lets see what is ZRC (Zoho Request Client) and how we can use ZRC methods in Client Script to get inputs from a Salesperson and update the Lead status with a single button click. In thisKaizen #222 - Client Script Support for Notes Related List
Hello everyone! Welcome to another week of Kaizen. The final Kaizen post of the year 2025 is here! With the new Client Script support for the Notes Related List, you can validate, enrich, and manage notes across modules. In this post, we’ll explore howKaizen #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 are
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
Copy paste settings
Hello all i have 2 organizations running in ZOHO books in one organization i have customised Tax rates, codes and customized templates instead of manually doing again in org 2 can i have some shortcut to copy paste or export and import??Custom TDS on Vendor Credits via API
Hi, We are using Zoho Books APIs for posting Bills and vendor credits. We are unable to post custom TDS amount posting vendor credits. Can you please share the API spec and Payload that need to be sent for Custom TDS for Vendor Credits."Unlink" Advance from Bill without Deleting the Payment Record
I am writing to highlight a significant workflow issue in Zoho Books (India Edition) regarding Vendor Advances and Bills. The Scenario: I recorded an Advance Payment to a vendor. I matched/reconciled this payment in the Banking module. I received a BillWhat is the best way to convert MSG file to Word format?
The best way to convert MSG files to Word format is by using a reliable and professional tool Aryson MSG file Converter. Manual methods are often time-consuming and may not preserve email formatting, attachments, or metadata accurately. In contrast, ArysonInvoice template with sales tax totals
Hi everyone, I am trying to edit my invoice template so that only the total sales tax collected for my tax group shows up. Right now, under by sub total, each individual tax shows up and that takes up a lot of unnessary space, so I just want the oneZoho Delayed Posting & Loss of Article Thumbnails on BlueSky
Hello! I am wondering if anyone else has had the either of the following issues when posting to socials via Zoho and if there is a fix? 1. Post says it is scheduled or it is live when sent off via Zoho but it doesn't show up on socials till some timeConnection Not Secure (Certificate Mismatch) Error
Hi, Just a fyi, when you go to https://bigin.zohocloud.ca/bigin/Home you get a "Your Connection Is Not private" error. (Certificate mismatch to domain.) I get to that page after I have signed up and signed in as a customer and select the Access BiginRecording the Investment
Hello, - One Investor Invested to our company, So how do we record investment which we received in our bank in the Zoho books ? - How do we record if we provide shares to the investor in the Zoho books? ThanksClient and Vendor portal at the same time
We have companies that serve both as clients and vendors and they are linked. However, we have a problem giving them access to the vendor/client portal. If they accept the invitation from the client portal, when we try to invite them to the vendor portalIntegrate Multiple ZohoBooks organization with zoho projects
We have successfully connected our Zoho Books with Zoho Projects for synronizing timesheet data. Our Business specialty is, that the staff of the Main company (A) is working on several projects, but the Clients are sometimes contracted and paying to aWays to calculate the difference form two years or months
Hi to everyone I have this request: I need to show the difference or variation from two periods (years or months) whether using a Pivot View or a graph, in this is case is better in a Pivot view. In the pivot view I will have the amount or results fromCareer site URL - Suggestion to modify URL of non-english job posting
Hi, I would like to suggest making a few modification to career sites that are not in english. Currently, the URL are a mix of different languages and are very long. It makes for very unprofessional looking URLs... Here is an example of one of our URLIntroducing Contract Settings & Backdated Contracts in Zoho Contracts
We are rolling out updates that give you more control over how contracts are created and managed in Zoho Contracts. From defining default workflows with Contract Settings to aligning agreements with real timelines using Backdated Contracts, these enhancementsCelebrating our customers on International Client's Day
Hi everyone, Every customer is part of our Zoho Desk family, and we wouldn’t want to miss celebrating you on this special day. This International Client's Day, we’d like to take a moment to appreciate every customer who has helped us grow and build meaningfulFaster Ticket Response with use of Snippets in comments
Hello everyone, Responding to tickets often involves repeating the same messages, whether it is sharing updates with customers or leaving notes for internal collaboration. To make this easier and more consistent, we are allowing agents to use snippetsImproving Zoho Creator's email deliverability
Hi all, We're pleased to announce updates to email handling in Zoho Creator to improve the deliverability of the emails sent from the Creator platform. These updates have been designed keeping in mind the fact that emails from domains with strong senderWhat's New in Zoho Billing | February 2026
February brings a powerful set of updates to Zoho Billing, from smarter subscription management and flexible payment options to better reporting and more control over your hosted pages. Here's everything that's new this February. Create SubscriptionsReassign Partially Saved Entries
Hi, I would like to be able to go to Partially Saved Entries and like the option to delete them I would like the option to multi-select and be able to reassign them to another user to complete (Such as when a user has left the company). Thanks DanDisplaying only unread tickets in ticket view
Hello, I was wondering if someone might be able to help me with this one. We use filters to display our ticket list, typically using a saved filter which displays the tickets which are overdue or due today. What I'd really like is another filter thatIssue creating a YTD report with last years numbers
I am looking to create a widget to compare the YTD leads we have in 2023 to the YTD leads we had in 2022. I'm having issues with the aggregate formula creation to gain access to the 2022 Leads YTD data point. Feeling like this is a common view of dataBrand Studio Projects in Analytics
Hi All, Currently pulling my hair out over trying to link together some social media posts for a reporting dashboard in Analytics, so I thought I'd see if anyone on here had a solution. Our Marketing Team created a LinkedIn campaign in Zoho Brand Studio,Manage Testing Process in Zoho Sprints
Agile framework supports a robust quality assurance system that incorporates continuous testing throughout the development lifecycle of the product. The agile testing team focuses on planning the testing around the development, identifying defects earlyAnnouncing the Zohotshots of the ZDC Hackathon 2025
Hey everyone, The wait is finally over! After weeks of building, experimenting, and pushing creative boundaries, we’re excited to announce the winners of the second edition of the ZDC Hackathon. This edition brought together an incredible community ofZOHO CRM Button Integration
Hi Team, I’m currently working with Zoho CRM along with a custom application where I fetch deal details from the CRM and use them based on my requirements for each deal. Now, I want to enhance this setup. I plan to create a button on the Deal Detail pageMajor journey crash and not loading. Zoho Marketing Automation
Hi all. Last night (19MAR, 2026) Marketing Automation for a specific journey completely crashed, and since the crash the specific journey has failed to load at all (blank journey canvas, no journey appears, no menu accessible) but other separate journey'sSubtotals per Header
Hey, we would like to display subtotals per header in our invoices:Candidate Assessments, no workflows.
I have an issue where I would like to trigger a workflow based on a candidate assessment being completed. Sometimes a returning candidate will complete a second assessment, on completion the status of the candidate will be updated to "Unqualified" ifMail Merge in Zoho Desk
Hello Team, Do we have an option of mail merge within Zoho Desk like we have in Zoho CRM? We have a requirement to generate some pdf file in the form of mail merge doc from the ticket.Support Required for Integrating Zoho SalesIQ in Flutter Web
Hi Team, I have developed a Flutter application and I am currently using the salesiq_mobilisten: ^6.5.4 package. As per the package documentation ( https://pub.dev/packages/salesiq_mobilisten ), it supports only Android and iOS, and it is working fineZoho vault filling in a form it's not supposed to fill in
Hey there, I have a problem with ZOHO Vault autofill. In a software package, we have these options: For some reason zoho vault always replaces what's in the top option and fills a 2fa password in there, and then saves that value.. Meaning whatever wasZoho Booking Integration with Desk
Just wanting to share something in case it helps someone else who may run into a similar use case as we did. Issue: Currently, the Zoho Booking integration with desk will drop a comment into the ticket when a customer books a time, however it won't changeLet us view and export the full price books data from CRM
I quote out of CRM, some of my clients have specialised pricing for specific products - therefore we use Price Books to manage these special prices. I can only see the breakdown of the products listed in the price book and the specialised pricing forSyncing calendar with Google Calendar doesn't work when events are sent to auto repeat
Hi... The ZOHO CRM -- GOOGLE CALENDAR sync is broken. If I create a single event on either side, sync works, but if I create an event with auto repeat on either side it doesn't work. Furthermore, events created before the sync don't show up in the calendar.Organization wide Account and Contacts Visibility/Sharing Capabilities?
Has anyone figured out a way to make visibility or sharing of Accounts and Contacts to be available across the entire organization without having to have every individual user edit their Sharing permissions? For our sales folks they need to be able toNotification of Interaction Assignment
If a user is assigned an interaction, they should be notified via email. These are almost useless because if I assign an interaction for someone to respond to, they dont know that I assigned it to them without me telling them or them logging in and discoveringCountries List Global Set- Complete with Phone Country Code and Continent.
Dear Zoho Team I saw your recent addition to the Global Sets regarding the Countries list and states. While working on it, why didn't you also add things like Continent and Phone Country Code? Also, some ISO codes from some Countries/regions are misCustom Display Field for Lookup Dropdowns in Zoho CRM
Could Zoho CRM support changing the display field in lookup dropdowns, like Zoho Creator does? This would make it much easier to select the right record by showing a more useful field instead of only the default one. It would improve speed, clarity, andMessage as bot
I would like to be able to send a Cliq message truly as a bot. the current implementation of this function, while it sends the message as a bot it sends that message inside a chat from the user how authenticated the flow cliq connection instead of directlyA2P 10DLC Opt-in Rejection Issue with Zoho Creator Public Form
Hi everyone, I’m working on an A2P 10DLC SMS campaign and running into repeated rejections due to opt-in issues. I’m using Zoho Creator for the registration flow. The form is public (no login required). Users enter their phone number and there is an uncheckedTrouble with using Apostrophe in Name of Customers and Vendors
We have had an ongoing issue with how the system recognizes an apostrophe in the name of customers and vendors. The search will not return any results for a name that includes the mark; ie one of our vendors names is "L'Heritage" and when entering theNext Page