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
DKIM cannot be enabled for the domain as no verified default selector present
Hi Support Team, For Domain DKIM record trying to enable status. but showing error "DKIM cannot be enabled for the domain as no verified default selector present" So, please resolve the issue. Thank you.unable to send message reason 554 5.1.8 Email outgoing blocked
unable to send message reason 554 5.1.8 Email outgoing blockedI can't log in to my account on Thunderbird
I've just had to rebuild my PC (calamitous mess from Microsoft with Win10/Win 11 'upgrade' - they confirmed I had to start with a new build). I have used Zoho mail for years via Mozilla Thunderbird, but now I've had to download the latest version of TBird,Should I Use DMARC?
When I configure Zoho Mail's DMARC settings, it's mandatory to fill in the RUA and RUF (Aggregate notification email address*, Forensic notification email address*) addresses. When we enter an email address in these fields, we receive reports from theIntroducing Profile Summary: Faster Candidate Insights with Zia
We’re excited to launch Profile Summary, a powerful new feature in Zoho Recruit that transforms how you review candidate profiles. What used to take minutes of resume scanning can now be assessed in seconds—thanks to Zia. A Quick Example Say you’re hiringBooks API Receiving an Error that Doesn't Make Sense when Creating Credit Note - trying to use 'ignore_auto_number_generation' argument
Hello, I'm working on a newly created routine and I'm getting an error that doesn't make sense when trying to create a new Credit Note. Here is my POST request. Endpoint: https://www.zohoapis.com/books/v3/creditnotes?organization_id=########## Body: {How to move emails to Shared Mailbox?
Hello, I created a Shred Mailbox instead of using a distribution group. But I cannot move previous emails to certain shared mailbox. Is it possible move some emails from inbox to shared mailbox?Collaboration with free plan user.
Hello. Do both users need to be on Pro plan to collaborate? Or can a Pro user share a note with a free plan user with the ability to edit?Zoho Inventory Now Supports VeriFactu for Businesses in Spain
Starting from January 1, 2026, Spain requires real-time invoice reporting for all B2B transactions. From July 2026, this requirement will extend to B2C transactions as well. All reporting must be carried out through the VeriFactu to AEAT (Agencia EstatalConnection to other user
Zoho Cliq handles sharing of Custom OAuth Connections that require individual user logins.In arattai received message can't be deleted
The issue has been noticed in following: arattai app (Android) arattai app (Window) arattai web While the message posted by me may be deleted, the ones received from others can't be. The item <Delete> change to <Report> when the message is a receivedAnalytics Portal
I have the "standard plan" and want to explore the portal option; I activated the 15-day trial but do not see the pricing for the add-on. How can I get the price under "Upgrade add-ons." Thanks RudyCan I filter a Lookup field to only show related records from another Lookup in Zoho CRM?
In our Leads module, we have two Lookup fields: Recruitment Agency – the agency that the lead came from Recruiter – the individual contact from that agency who sent us the lead Both fields link correctly to their respective records in CRM. However, ourZoho Books API invoice email bouncing with 'relaying-issues' error
I have waited over 30 days for zoho books uk to assist with the following and i have had no replies or tickets erronously closed. The service has been terrible - very unlike zoho! So i am raising this here hoping that a community member can assist: Hello,How do I filter contacts by account parameters?
Need to filter a contact view according to account parameter, eg account type. Without this filter users are overwhelmed with irrelevant contacts. Workaround is to create a custom 'Contact Type' field but this unbearable duplicity as the information alreadyZoho Writer to Zoho Sign Template Misalignment – Request for Community
We are currently facing a critical issue impacting our live business operations due to a misalignment problem between Zoho Writer templates and Zoho Sign output. Issue Summary: We have an automated workflow in Zoho CRM using Deluge scripts that generatesAccount blocked
Yesterday I got my Zeptomail account blocked due to too many hard bounces. My account is used exclusively for sending transactional emails (eg. your order has been shipped, a form has been filled, etc) and the sudden blocking impacted hundreds of websitesMigration Tool Download
Since apparently you have to ask for the migration tool to download (why?), I need the download for the migration tool for exchange servers. Please forward link, thanks.IF Formula
Hi, I'm having trouble setting up a custom formula in a field. Can you help me with it? The formula should do the following: If the created date is less or equal to 30 days the field should display a string New in pieline or Exisitng pipeline if aboveAutorespond to one specific sender
Is there any way to create a rule or filter that sends an automatic reply to messages from one specific email address? I really need to set up something like a "vacation response" but only for one "received from" address.View comprehensive logs of all actions in Custom Module History
Hello everyone, We are happy to announce our new feature, Detail View in Custom Module History, which enhances visibility, control and accountability over your records. Users can now access a detailed timeline of every action that has been performed onTrack ZohoForm Conversion using Postmessage event
Hi, I’ve been using a third-party lead tracking tool to capture leads from my website along with their source. Earlier, with the HubSpot form, the third-party script was able to detect the postMessage event that iframe forms typically send back to theEmail task creator when task is updated/marked complete
I am looking for a way to notify the creator of a task in zoho todo when - Task is updated Task is closed Comments entered 1 and 2 are critical, and I cannot find a zoho flow to do this. There is no way that as a manager I will know when someone has completedEmail Recall Feature In Zoho Mail Which Should Also Work For Outside Organisation Members
Add a feature to recall or undo sending an email within a configurable short time window (e.g., 30 seconds to 2 minutes) after hitting send, similar to Gmail’s undo send. Currently the sent email can not be recall If the recipient is not from within yourHow to implement calculating average value of averaged values?
Hi, I'm trying to implement a formula in my layout for a module that calculates the average of 2 averaged values, but I can't do so using the formula custom field. To calculate the 2 averaged values, I could use the formula custom field, but in the customZoho Recruit update published job boards
If we have a job thats already posted on several different job boards and we edit this job in zoho recruit (e.g. the description of the job), does this then automatically update this new information to all the published job boards? If not, how does theNarrative 14: The magic bazaar of Desk
Behind the scenes of a successful ticketing system: BTS Series Narrative 14: The magic bazaar of Desk Marketplace is a centralized platform where users can discover Zoho and third-party applications that can be integrated with their Desk account to facilitateCollections Management: #2 Late Payment Automation
"Sir, I'll process the payment by evening, please don't apply any late payment charges", the customer said while arranging papers on his desk. Sanjay stood there with a tired smile. He had already visited twice that week. Payment collection was one thing.Create a table in the layout section of modules
Dear Sirs, I would like to know whether is possible to create a table under new fields in layouts section of modules. In fact in this section there are single line, multi line, pick list, multi-select, date, formula etc. but I am unable to add a tableNimble enhancements to WhatsApp for Business integration in Zoho CRM: Enjoy context and clarity in business messaging
Dear Customers, We hope you're well! WhatsApp for business is a renowned business messaging platform that takes your business closer to your customers; it gives your business the power of personalized outreach. Using the WhatsApp for Business integrationPower of Automation :: Automatic Task Status Handling for Users
Hello Everyone, A custom function is a software code that can be used to automate a process and this allows you to automate a notification, call a webhook, or perform logic immediately after a workflow rule is triggered. This feature helps to automateQuestion - why no way to input a 'tool description' and 'tree of 'tools'
Every business is different, with different business processes. To be truly useful Zoho MCP needs to have user editable tool descriptions (or ruleset) and a 'tool tree' so that the LLM is context aware when being used. For example, the tool descriptionDevelop Zoho Meeting as a Full Native Application (Not a Browser Wrapper)
Hello Zoho Meeting Team, Hope you are doing well. We would like to suggest an important improvement regarding the Zoho Meeting desktop application. At the moment, the Zoho Meeting app feels more like a mini browser window or an iframe that loads the webCan I create a custom function for chart of accounts?
I'm trying to add a custom function that should run whenever a record in the Chart of Accounts module is edited, but on the form for creating a new function, the module dropdown does not include the chart of accounts as an option.billing
hi, I am being billed $12/year, and I can't remember why. My User ID is 691273115 Thanks for your help, --Kitty PearlAutomatic Matching from Bank Statements / Feeds
Is it possible to have transactions from a feed or bank statement automatically match when certain criteria are met? My use case, which is pretty broadly applicable, is e-commerce transactions for merchant services accounts (clearing accounts). In theseUnable to confirm Super Admin assignment — confirmation button not working
I’m trying to change the roles within my organization. I am currently a super admin and would like to add another user as a super admin. When I attempt to confirm the action, a screen appears asking for my password to verify my identity. However, whenAutomation#36: Auto-create time-entry after performing the Blueprint transition
Hello Everyone, This week’s edition focuses on configuring a custom function within Zoho Desk to streamline time tracking within the Blueprint. In this case, we create a custom field, and request the agent to enter the spending time within the singleFeature Request: Reviews
Any chance we could get a "Reviews" element to put on sites? It should be extremely simple to do. Basically just take the comments box and add an option for a star rating. At the very least, it would be nice to have more customization options for the comment box so the text could be changed from "Comments" to "Reviews". I've looked at a bunch of embeddable review widgets but nothing meets my needs so this would be a great feature to have added to the site builder.Can we handle a support like (incident management) project in Zoho Projects?
Hi, I have a new profile of a project whereby we provide "ticket" base support to a client. They have a request and ideally we would handle comms via a email exchange logged in Zoho. Today we use Zoho Projects for all out projects, which means that weNext Page