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 #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 theKaizen #197: Frequently Asked Questions on GraphQL APIs
🎊 Nearing 200th Kaizen Post – We want to hear from you! 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.
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
Can we generate APK and IOS app?
Dears, I want to know the availability to develop the app on zoho and after that .. generate the APK or IOS app and after that I added them to play store or IOS store.. Is it possible to do this .. I want not to use zoho app or let my customers use it. thanksLimitation with Dynamic Email Attachment Capture
I've discovered a flaw in how Zoho Creator handles email attachments when using the Email-to-Form feature, and I'm hoping the Zoho team can address this in a future update. The Issue According to the official documentation, capturing email attachmentsWhy is Zoho Meeting quality so poor?
I've just moved from Office 365 to Zoho Workplace and have been generally really positive about the new platform -- nicely integrated, nice GUI, good and easy-to-understand control and customisation, and at a reasonable price. However, what is going onZoho Learn Course Completion Notifications/Triggers/API
Zoho Learn works great and will suit our course creation needs, but it appears to be lacking a bit when it comes to integration with other Zoho services (creator etc.) when it comes to course completion. 1) Is there an API or Zoho Flow trigger for whenSorting a list of record acquired from the zoho.crm.searchRecords function.
This is something for which I'm trying to figure out a straightforward way to do. The searchRecords does a great job fetching me the records that I want. However, in some cases, where it returns multiple records, I want it to sort the returned list by date of creation of that record, so that when I do records.get(0), I get the most recent record. As an example, here's my sample pseudo code: records = zoho.crm.searchRecords("Clients", "Office_Number:equals:123456"); Now the "records" list above containsEnhanced Recording Permission Controls for Zoho Cliq Meetings (Similar to Zoom)
Hello Zoho Cliq Team, We hope you are doing well. We would like to request an enhancement to the recording permission functionality in Zoho Cliq Meetings. Current Limitation: in Zoho Cliq Only hosts and co-hosts can record a meeting. Participants cannotPhone Connection
When on a call the person on the other end complains that there is static, I am cutting in and out or they can't hear me all. This happens on the cell connection as well.Ability to Edit YouTube Video Title, Description & Thumbnail After Publishing
Hi Zoho Social Team, How are you? We would like to request an enhancement to Zoho Social that enables users to edit YouTube video details after the video has already been published. Your team confirmed that while Zoho Social currently allows editing theCan't add a sender adress from zoho campaigns
hi, I need to change the sender address for a campaign. When i try to add it i get a message to say 'duplicated email address found while adding your sender address'. This is the first campaign i'm sending so I don't understand why this message is displayed? Thanks JaneAdmin asked me for Backend Details when I wanted to verify my ZeptoMail Account
Please provide the backend details where you will be adding the SMTP/API information of ZeptoMail Who knows what this means?This domain is not allowed to add. Please contact support-as@zohocorp.com for further details
I am trying to setup the free version of Zoho Mail. When I tried to add my domain, theselfreunion.com I got the error message that is the subject of this Topic. I've read your other community forum topics, and this is NOT a free domain. So what is theThis user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details
Hello, Just signed up to ZOHO on a friend's recommendation. Got the TXT part (verified my domain), but whenever I try to add ANY user, I get the error: This user is not allowed to add in Zoho. Please contact support-as@zohocorp.com for further details I have emailed as well and writing here as well because when I searched, I saw many people faced the same issue and instead of email, they got a faster response here. My domain is: raisingreaderspk . com Hope this can be resolved. Thank youNeed Faster Help? Try Live Chat Support
Hello there, We understand that sometimes, whether you’re facing an issue, exploring a feature, or need quick clarification, sending an email and waiting for a response just doesn’t cut it. You need answers, and you need them now. That’s exactly why weExport History timeline
Hi, I have an idea, bout zoho desk history of the ticket it would be great if the agent or admin of the zoho desk can export the timeline of the ticket history for agent report or on other matter.Desk fails to create a new ticket on Reply email
When I send a direct email to support@mysite.com, Desk will create a new ticket as expected. When I REPLY to an email sent from support@mysite.com, Desk will NOT generate a new ticket. This is very bad. How can I fix this? Use case: In a separate systemCondition based aggregate fields in subforms
Hello everyone, We're excited to inform you about the latest enhancements made to our aggregate field capabilities in subforms; create aggregate fields based on conditions! An aggregate field is a column on which a mathematical function has been applied.Ask the Experts 25: Experience the full spectrum of Zoho Desk’s autumn and spring releases for 2025
Hello Everyone, We’re on the 25th episode of our ATE series! It's a true milestone in our live community interactions! It’s been an amazing journey since we started in October 2018. Zoho Desk has come a long way, evolving with the support of a wonderfulPrinting Multi-Page Reports (PDF Export)
Hi, I am moving a report from Google's Looker Studio to Zoho Analytics and trying to reproduce the Looker page by page dashboard editing experience. With Google, what you see is what you get when you print to PDF. But I can't seem to create the same experienceAddin Support in Zoho Sheet
Is there any addin support available in zoho sheet as like google marketplace to enhance productivity by connecting with other apps, providing AI data analysis, streamlining business processes, and more?Mass Update of Lookup Fields not possible
Hello List I've created a custom field for Leads and Contacts 'Current Campaign'. This is very Handy as I can filter leads and then related them to a campaign. Everything ready, but then I realized that mass update doesn't work for lookup fields... aZoho Books | Product updates | November 2025
Hello users, We’ve rolled out new features and enhancements in Zoho Books. From translating email notification templates to the new transaction locking restrictions, explore the updates designed to enhance your bookkeeping experience. Making Tax DigitalFunction #61: Automatically add free item to the invoice based on item quantity
Hello everyone, and welcome back to another Custom Function Friday! During holiday seasons or special promotions, businesses offer deals like BOGO (Buy One, Get One), Buy 3 Get 1 Free, Buy 2 at 50% off, and much more to attract customers. These promotionsNotes for Items for Future Purchase Order
Next time when I order an item, tau have to make some changes in it, that order has to be placed after 4-5 months, I want to save those changes or points somewhere in the item, how will that be possible..Schemes of different tyoe
How can easily apply hourly, day wise or month wise schemes on Bill, Quantity, and other schemes. Like I want to apply a scheme Form today to next 7 days .where i can mention in zoho books so scheme will implement automatically to all customers andAlphabetically
How can i arrange alphabetically - (Manage Manufacturer) Field in Item MasterClients not receiving emails
I've been informed that my emails are not being received. Is there anything that I should look into to rectify this? Many thanks!Double opt-in notifications and customizable confirmation messages for your webforms
Dear CRM Community, We are excited to announce a major upgrade to our Webforms feature. You can now customize the confirmation message shown to your users who double opt-in from your webform and also customize your confirmation emails when they submitEnterprise subscription support
My organization sells subscription services to enterprise customers, which is a different model from the consumer subscription model that Zoho Billing has been designed to support and I beleve this capability should be added. An enterprise subscriptionRecruit paid support?
Hi all, Could anyone who has paid support package advise if it provides value for money with regards to support response times? Exploring the idea as unfortunately when we have faced issues with Recruit it has been a 7+ day timescale from reporting toFree Plan mail accounts details
In the zoho mail pricing there's a free plan that includes: FREE PLAN Up to 25 Users 5GB* /User, 25MB Attachment Limit Webmail access only. Single domain hosting. I need to make sure that I'm able to create multiple email accounts in the form of: name@domain.comZOHO Mail App Not working
There seems to be an issue with Zoho Mail App today. It is not connecting to server, internet is working fine, tried uninstalling app and reinstalling, loading circle keeps spinning round. Is there an update on the way?No more IMAP/POP/SMTP on free plans even on referrals with NO NOTICE
Outraged. Just referred a colleague to use her domain (not posting it publicly here) to Zoho, just as I have other colleagues, clients, friends. Expected the exact same free plan features as I have and as everyone else I ever referred got. I was helpingUnable to receive email - "5.3.0 - Other mail system problem 554-'5.2.3 MailPolicy violation Error delivering to mailboxes'"
My users are unable to receive emails from one particular domain, apparently. The domain known to be kicked back is whitelisted in the spam control. I sent an email to support earlier this morning but I have not received a reply. The error in the titleCaixa de saída bloqueada. Como desbloquear?
Olá, meu e-mail isabela.celli@sivirino.com está com a caixa de saída bloqueada. Não consigo enviar e-mails. Acredito que tenha sido porque mandei o mesmo e-mail para várias pessoas, pedindo uma cotação de serviço. Vocês podem desbloquear para mim? QuantosZoho Forms - Improve the CRM integration field to query data from more than one module
Hi Forms team, Something I get stuck on regularly is pre-populating a form with data when that data is spread across 2 or 3 modules. For example Contacts, Accounts and Deals. I don't want to duplicate the information in CRM so I end up writing a functiondesbloquear cuenta
Buenos dias Cordial saludo Tengo una cuenta libre en zoho mail asociado a un dominio, pero uno de los usuarios se bloquea el correo porque dice que ha excedido el límite de correo, por favor podrian desbloquearla y como hago para que esta persona debe enviar sus correos sin ningun probleama. Gracias de antemanoNot Receiving Incoming Mail
I can send emails from my account but I do not receive any. I originally set up forwarding and it worked for a while and then stopped. I turned off forwarding and now do not receive any emails. Could you please check what is causing this issue? Thank youWill zoho thrive be integrated with Zoho Books?
titleBARCODE PICKLIST
Hello! Does anyone know how the Picklist module works? I tried scanning the barcode using the UPC and EAN codes I added to the item, but it doesn’t work. Which barcode format does this module use for scanning?Making preview pane "stick"
Hello, Is it possible to fix/dock the preview pane so that it's always there? The modern monitors are all very wide so there's plenty of space horizontally. Having the preview pane disappearing and appearing again when you click on an email message inNext Page