Kaizen #13 - Bulk Write API
Hello everyone!
Welcome to yet another post in the Kaizen series.
This week, we are going to discuss the Bulk Write API.
What is the Bulk Write API?
The bulk write API allows you to insert, update, and upsert records in a module in Zoho CRM in bulk. The primary difference between the bulk write API, and the Insert, Update, Upsert records API, is the number of records that you can handle.
While you can insert, update, and upsert, only 100 records via the Insert, Update, and Upsert Records API per call, you can handle 25000 records via a Bulk Write API call.
When you should use the Bulk Write API?
- When you want to insert, update, or upsert more than 100 records per API call.
- When you want to perform background processes like migration and initial data sync between Zoho CRM and external services.
Below are the differences between Insert, Update, Upsert Records API and the Bulk Write API.
Insert, Update, Upsert Records | Bulk Write API |
You can insert, update, or upsert only 100 records per API call. | You can insert, update, or upsert 25000 records per API call. |
The response is available instantly. | The response is not available instantly; the bulk write job is scheduled, and the status is available after job completion in the callback URL. |
You will receive a success response. | A downloadable ZIP file containing a CSV file, is available with ID, status, and errors if any. |
How does the Bulk Write API work?
To insert, update, or upsert records in bulk, follow the below steps:
- Prepare your CSV file
- Upload your file
- Create a bulk write job
- Check the job status
- Download the result
Now, let us see each step in detail.
1. Prepare your CSV file
The Bulk Write API only accepts a CSV file compressed into a ZIP file as input. The first row should contain the field API names. Refer to the field metadata API, to get the field API names. Each subsequent row contains the data to be written in Zoho CRM. You can insert, update, or upsert records only in a single module through one bulk write API call. Refer to attachments to get a sample ZIP file to bulk-insert contacts.
Input format for each data type
Datatype | Description |
Single Line | Accepts up to 255 characters. Accepts alphanumeric and special characters. Ex: Mike O'Leary |
Multi-Line | Small - accepts up to 2000 characters. Large - accepts up to 32000 characters. Ex: This is a sample description. |
Email | Accepts valid email IDs. |
Phone | Accepts up to 30 characters. This limit may vary based on the value configured in 'Number of characters allowed' in the properties pop-up of the field, in UI. Accepts only numeric characters and '+' (to add extensions). Ex: 9800000099 |
Picklist | You can pass an existing pick list value. If you give a new one, it is automatically added to the pick list set. The pick list value accepts all alphanumeric and special characters. Ex: auto mobile |
Multiselect Picklist | You can either pass the existing pick list values or add a new one. The values are separated by semicolon(;). The pick list value accepts all alphanumeric and special characters. Ex: Analytics;Bigdata |
Date | Accepts date in yyyy-MM-dd format. Ex: 2019-08-28 |
| Date/Time | Accepts date and time in yyyy-MM-ddTHH:mm:ss±HH:mm ISO 8601 format. |
Number | Accepts numbers up to 9 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. Accepts only numeric values. Ex: 350 |
Currency | Before the decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. After the decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal paces' in the properties pop-up of the field, in UI. |
Decimal | Before the decimal point - accepts numbers up to 16 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. After the decimal point - accepts precision up to 9 digits. This limit may vary based on the value configured in 'Number of decimal places' in the properties pop-up of the field, in UI. Accepts only numeric values. Ex: 250000.50 |
Percent | Accepts numbers up to 5 digits. Accepts only numeric values. Ex: 25 |
Long Integer | Accepts numbers up to 18 digits. This limit may vary based on the value configured in 'Maximum digits allowed' in the properties pop-up of the field, in UI. Accepts only numeric values. Ex: 0012345600012 |
Checkbox | Accepts Boolean values (true,false). Ex: true |
URL | Accepts valid URLs. |
Lookup | Accepts the unique ID of the record, which you can get through the get records API. Use the dot(.) operator to link the record. For instance, if there is an account lookup in the Contacts module, you can give the column name as Account.id Ex: Account.id : 4150868000001136302 |
Note:
Multiselect and User datatype fields are not supported in Bulk Write.
Here is a sample content for a CSV file with different field types.
Note:
- To give multiple values for a multi-select pick list field, enclose them in double quotes("") and separate each value with the semicolon(;).
- If your multi-line field has more than one line, input them directly by enclosing them in double quotes("").
2. Upload your CSV file
This involves making a POST API call, with the ZIP file containing the required data. The file is passed as form-data input, with key as file. When the call is successful, you will receive a file_id which you can further use to create a bulk write job.
Headers
Header Name | Description |
feature | bulk-write |
X-CRM-ORG |
3. Create a bulk write job
In this step, make a POST API call with the file_id obtained from the previous step, the callback URL, operation type (insert, update, upsert), module, and field API names. When the call is successful, you will receive a job ID in the response. You can use this ID in another request to poll for the status of the job.
Request URL
{{api-domain}}/crm/bulk/v2/write
Sample Input for bulk insert
{ "operation": "insert", "callback": { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }, "resource": [ { "type": "data", "module": "Contacts", "file_id": "4150868000001038001", "field_mappings": [ { "api_name": "Last_Name", "index": 0, "default_value": { "value": "DefaultValue" } }, { "api_name": "Email", "index": 1 }, { "api_name": "Phone", "index": 2 } ] } ] } |
Sample Input for Bulk Update
{ "operation": "update", "callBack": { "url": "https://sampledomain.com/getzohoresponse", "method": "post" }, "resource": [ { "type": "data", "module": "Contacts", "file_id": "4150868000001123001", "field_mappings": [ { "api_name": "Last_Name", "index": 0 }, { "api_name": "Email", "index": 1 }, { "api_name": "Phone", "index": 2, "ignore_empty": true } ], "find_by": "Email" } ] } |
Input Keys
Key | Description |
operation string, mandatory | The operation to be done. The possible values are—insert, update, upsert. insert - To insert records in bulk. update - To update existing records in bulk. upsert - To update if the record exists or insert the record. |
callback JSON object, mandatory | The callback details. Contains callback URL in the "callback" key and the "method" as post. |
resource JSON array, mandatory | The details of the data in the ZIP file that is uploaded.
|
field_mappings JSON array, mandatory | The details about the fields given in the CSV file. Each object corresponds to each field in the CSV file. Mention the position of the fields in the CSV file in the "index" key, that must start from 0. "default_value" key can be used when a few fields are left blank, and you want the system to fill the default details. |
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. |
find_by string, mandatory (for Update and Upsert) | The system finds the record to be updated by the "find_by" field. It must be a unique field configured in Zoho CRM. To check the same, go to Setup > Modules and Fields > Choose Module > Choose Layout > Choose the field > Click on more options > Check if Do not allow duplicate values is enabled. |
4. Check job status
The Bulk Write API supports polling and callback.
Polling
You can poll to check the status of the scheduled bulk write job with the job ID you received in the previous step.
Request URL: {{api-domain}}/crm/bulk/v2/write/{job_id}
Request Method: GET
Sample Response
- The status can be either ADDED, INPROGRESS, or COMPLETED. Only the COMPLETED jobs will have the "download-URL" key in the response.
- The "file" JSON object in the response represents the total count of records (added, skipped, updated). If the status is mentioned as "skipped" for any record, the reason will be displayed under the ERRORS column, in the downloaded ZIP file.
{ "status": "COMPLETED", "character_encoding": "UTF-8", "resource": [ { "status": "COMPLETED", "type": "data", "module": "Contacts", "field_mappings": [ { "api_name": "Email", "index": 1, "format": null, "find_by": null, "module": null, "default_value": null }, { "api_name": "Last_Name", "index": 0, "format": null, "find_by": null, "module": null, "default_value": { "name": null, "module": null, "value": "DefaultValue" } }, { "api_name": "Phone", "index": 2, "format": null, "find_by": null, "module": null, "default_value": null } ], "file": { "status": "COMPLETED", "name": "Contacts.csv", "added_count": 7, "skipped_count": 0, "updated_count": 0, "total_count": 7 } } ], "id": "4150868000001060014", "callback": { "method": "post" }, "result": { "download_url": "https://download-accl.zoho.com/v2/crm/694902309/bulk-write/4150868000001060014/4150868000001060014.zip" }, "created_by": { "id": "4150868000000225013", "name": "Patricia Boyle" }, "operation": "insert", "created_time": "2020-01-03T15:19:52+05:30" } |
Callback
If you do not want to poll for the status of the job, you can wait for the system to notify you of job completion on the callback URL provided in the POST request.
- The state indicates the successful completion ("state":"COMPLETED") or failure ("state":"FAILED") of the job.
- The callback response will also contain the download URL if the job was completed successfully.
5. Download the result
In this step you can get the result of the bulk write job in a ZIP containing the CSV file. Call the 'download_url' to download the result. The CSV file will contain the first three mapped columns from the uploaded file, and three more columns—STATUS, RECORD_ID, and ERRORS.
Request URL: {{api-domain}}/crm/bulk/v2/write/{job_id}/result
Sample Response
You can see that out of four records, one was skipped because the unique field had a duplicate value.
Limitations
- You can upload only one ZIP file per bulk write API call.
- You can bulk write to only one module per API call.
- The size of the ZIP file being uploaded must not exceed 25 MB. If the file size exceeds the size limit, you must split the file and schedule it as multiple bulk write jobs. Also, you can bulk write only up to 25000 records with 200 column headers per bulk write API call.
- Every successfully scheduled bulk write job reduces 500 credits from your daily credit limit.
- All the mandatory fields must be given in the CSV file if you are trying to insert records. Similarly, ID is mandatory when you are trying to update records.
- Subforms are not supported in Bulk Write.
- Consider that you have a lookup field in the Leads module, that looks up to other leads. You cannot have the value of this field as another Lead that is being written in this bulk write job. In other words, you can only lookup to an existing lead.
For limitations, refer to limitations in our API guide.We hope you found this post useful. If you have any further queries, reach out to us at support@zohocrm.com or let us know in the comments section.
Cheers!
Topic Participants
Sneha Sridharan
richie
Praveen Sankar
Andres
Access
Sticky Posts
Kaizen #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.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.Celebrating 200 posts of Kaizen! Share your ideas for the milestone post
Hello Developers, We launched the Kaizen series in 2019 to share helpful content to support your Zoho CRM development journey. Staying true to its spirit—Kaizen Series: Continuous Improvement for Developer Experience—we've shared everything from FAQsKaizen #193: Creating different fields in Zoho CRM through API
🎊 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.Client Script | Update - Introducing Commands in Client Script!
Have you ever wished you could trigger Client Script from contexts other than just the supported pages and events? Have you ever wanted to leverage the advantage of Client Script at your finger tip? Discover the power of Client Script - Commands! Commands
Recent Topics
Change of Blog Author
Hi, I am creating the blog post on behalf of my colleague. When I publish the post, it is showing my name as author of the post which is not intended and needs to be changed to my colleague's name. How can I change the name of the author in the blogs?? Thanks, RamananShow Attachments in the customer portal
Hi, is it possible to show the Attachments list in the portal for the particular module? Bests.Does Zoho Docs have a Line Number function ?
Hi, when collaborating with coding tasks, I need an online real time share document that shows line numbers. Does Zoho's docs offer this feature ? If yes, how can I show them ? Regards, FrankPlease make it easier to Pause syncing
right now it takes 3 clicks to get there. sounds silly, but can you make it just 2 clicks to get it done instead? thats how dropbox does it, 2 clicks to pause instead of 3.Feature Request - Insert URL Links in Folders
I would love to see the ability to create simple URL links with titles in WorkDrive. or perhaps a WorkDrive extension to allow it. Example use case: A team is working on a project and there is project folder in WordDrive. The team uses LucidChart to createOrganization Emails in Email History
How can I make received Org Emails to show up here?how to differentiate if whatsapp comes from certain landing page?
I create a Zobot in SalesIQ to create a Whatsapp bot to capture the lead. I have 2 landing pages, one is SEO optimized and the other want is optimized for leads comes from Google Ads. I want to know from which landing page this lead came through WhatsAppHow to sync from Zoho Projects into an existing Sprint in Zoho Sprints?
Hi I have managed to integrate Zoho Projects with Zoho Sprints and I can see that the integration works as a project was created in Zoho Sprints. But, what I would like to do is to sync into an existing Zoho Sprints project. Is there a way to make thatHow to record company set up fees?
Hi all, We are starting out our company in Australia and would appreciate any help with setting up Books accounts. We paid an accountant to do company registration, TFN, company constitution, etc. I heard these all can be recorded as Incorporation Costs, which is an intangible asset account, and amortised over 5 years. Is this the correct way to do it under the current Australian tax regulations? How and when exactly should I record the initial entry and each year's amortasation in Books? GenerallyHow to create a drop down menu in Zoho Sheets
I am trying to find out, how do I create a drop down option in Zoho sheet. I tried Data--> Data Validation --> Criteria --> Text --> Contains. But that is not working, is there any other way to do it. Thanks in Advance.Show Payment terms in Estimates
Hi, we are trying to set up that estimates automatically relates payment terms for the payment terms we introduced on Edit contact (Field Payment terms). How can it be done? Our aim is to avoid problems on payment terms introduced and do not need to introduce it manually on each client (for the moment we are introducing this information on Terms and Conditions. Kind Regards,Rich-text fields in Zoho CRM
Hello everyone, We're thrilled to announce an important enhancement that will significantly enhance the readability and formatting capabilities of your information: rich text options for multi-line fields. With this update, you can now enjoy a more versatileHow can I calculate the physical stock available for sale?
Hey Zoho Team, I've tried to calculate the physical stock on hand in various ways - but always receive a mismatch between what's displayed in Zoho Inventory & analytics. Can you please let me know how the physical stock available for sale is calculated?When dispatched to crew, assigning lead missing
Hello, For the past two or three weeks, whenever an officer assigns Service Appointment to a team, the lead person is missing from the assigned service list. Therefore, we have to reschedule the SA and then the lead person becomes visible in the assignedCreate Lead Button in Zoho CRM Dashboard
Right now to create Leads in the CRM our team is going into the Lead module, selecting the "Create Lead" button, then building out the lead. Is there anyway to add the "Create Lead" button or some sort of short cut to the Zoho CRM Dashboard to cut outopen word file in zoho writer desktop version
"How can I open a Microsoft Word (.doc or .docx) file in Zoho Writer if I only have the file saved on my computer and Zoho Writer doesn't appear as an option when I try 'Open with'? Is there a way to directly open the .doc file in Zoho Writer?"I want to transfer the project created in this account to another account
Dear Sir I want to transfer the project created in one account to another accountInactive User Auto Response
We use Zoho One, and we have a couple employees that are no longer with us, but people are still attempting to email them. I'd like an autoresponder to let them no the person is no longer here, and how they can reach us going forward. I saw a similarWeekly 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 justZoho Slowness - Workarounds
Hi all, We've been having intermittent slowness and Zoho just asks for same stuff each time but never fix it. It usually just goes away on it's own after a couple weeks. Given that speed is a very important thing for companies to be able to keep up withCustom Bulk Select Button
Zoho CRM offers the ability to select multiple records and invoke a Custom Button This functionality is missing from Recruit Currently we can only add buttons in the detail page and list But we cannot select Multiple Records and invoke a function withHow to create a Zoho CRM report with 2 child modules
Hi all, Is it possible to create a Zoho CRM report or chart with 2 child modules? After I add the first child module, the + button only adds another parent module. It won't let me add multiple child modules at once. We don't have Zoho Analytics and wouldZoho CRM still doesn't let you manage timezones (yearly reminder)
This is something I have asked repeatedly. I'll ask once again. Suppose that you work in France. Next month you have a trip to Guatemala. You call a contact there, close a meeting, record that meeting in CRM. On the phone, your contact said: "meet mePower of Automation :: Smart Ticket Management Between Zoho Desk and Projects
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 automateFirst day of trying FSM in the field.
What we found. 1. with out a network connection we were unable to start a service call? 2. if you go to an appointment and then want to add an asset it does not seem possible. 3. disappointed not to be able to actually take a payment from within the appBUG - Google Business Buttons - Add a button to GBP Post
I am experiencing an issue with the "Add a button" feature when creating posts for my Google Business Profile (GBP) through Zoho Social. When I schedule or publish a GBP post and include a call-to-action button with a specific URL, the post itself publishesRich text Merge field - Not using font specified in HTML
I have a rich text merge field in a writer template which is creating a table. I have chosen to use this method instead of a repeat region because I need to specify specific cell background colours which change every time the document is created. TheSupport for Custom Fonts in Zoho Recruit Career Site and Candidate Portal
Dear Zoho Recruit Team, I hope you're doing well. We would like to request the ability to use custom fonts in the Zoho Recruit Career Site and Candidate Portal. Currently only the default fonts (Roboto, Lato, and Montserrat) are available. While theseCC and/or BCC users in email templates
I would like the ability to automatically assign a CC and BCC "User (company employee)" into email templates. Specifically, I would like to be able to add the "User who owns the client" as a CC automatically on any interview scheduled or candidate submittedTrying to export a report to Excel via a deluge script
I have this code from other posts but it gives me an error of improper statement, due to missing ; at end of line or incomplete expression. Tried lots of variations to no avail. openUrl(https://creatorapp.zoho.com/<username>/<app name>/XLSX/#Report:<reportname>,"sameZoho Reports Duplicating Entries
I have a custom costing tab with a table where we entre invoices. These are under a Heading (PO Subject) and notes added in the form with different line items. In the reports, I have organised the report to group per PO Subject, with the total of theNeed help to create a attach file api
https://www.zoho.com/crm/developer/docs/api/v8/upload-attachment.html Please help me to create it... It's not working for while. Do you have some example?Export view via deluge.
Hi, Is it possible to export a view (as a spreadsheet) via deluge? I would like to be able to export a view as a spreadsheet when a user clicks a button. Thankshow to add subform over sigma in the CRM
my new module don't have any subform available any way to add this from sigma or from the crmOutdated state in mexico
Hello Zoho team, the drop down to add the state for customers, when they introduce their state in mexico has a city named “Distrito Federal” that name changed many years ago to “ciudad de mexico”. could you please update this so my clients can find theSupport new line in CRM Multiline text field display in Zoho Deluge
Hi brainstrust, We have a Zoho CRM field which is a Muti Line (Small) field. It has data in it that has a carriage return after each line: When I pull that data in via Deluge, it displays as: I'm hoping a way I can change it from: Freehand : ENABLED ChenillePossible to generate/download Quote PDF using REST API?
See title. Is there any way after a quote has been created to export to a PDF using a specified template and then download it? Seems like something that should be doable. Is this not supported in the API v2.0?Creating an invoice to be paid in two installments?
Hi there, I own a small Photographic Services business and have not been able to find a way to fit my billing system into Zoho, or any other Accounting software. The way my payments work is: 1. Customer pays 50% of total price of service to secure theirBug in allowing the user to buy out of stock items
Hi i want to allow the user to buy out of stock items, according to the commerce documentation if i disable Restrict "Out of stock" purchases it will, but it doesnt work, so i want to know if it had any relation with zoho inventory, and if theres anyZoho CRM Calendar | Custom Buttons
I'm working with my sales team to make our scheduling process easier for our team. We primary rely on Zoho CRM calendar to organize our events for our sales team. I was wondering if there is a way to add custom button in the Calendar view on events/meetingNext Page