Kaizen #12 - Bulk Read API
Hello everyone!
We hope you all are having a wonderful start in the New Year!
Welcome back to another post in the Kaizen series!
What is the Bulk Read API?
The Bulk Read API allows you to export data from a module in Zoho CRM in bulk. The primary difference between the GET records API and the Bulk Read API is the number of records you can retrieve.
While you can get only 200 records per Get records API call, you can fetch 200,000 records per bulk read API call.
When should you use this API?
- When you want to export more than 200 records through an API call.
- When you want to perform background processes like migration, data backup, and initial data sync between Zoho CRM and external services.
What is the difference between GET Records API and Bulk Read API?
GET Records
Bulk Read API
You can fetch a maximum of 200 records per API call.
You can fetch a maximum of 200,000 records per API call.
The response is available instantly.
The response is not available instantly; the bulk read job is scheduled, and the status is available after job completion in the callback URL.
The records are available as JSON objects in the response.
The records are available in a downloadable CSV file or ICS file (for events).
GET Records
Bulk Read API
You can fetch a maximum of 200 records per API call.
You can fetch a maximum of 200,000 records per API call.
The response is available instantly.
The response is not available instantly; the bulk read job is scheduled, and the status is available after job completion in the callback URL.
The records are available as JSON objects in the response.
The records are available in a downloadable CSV file or ICS file (for events).
What kind of export does the Bulk Read API support?
You can export
- Records available in a custom view. You can also apply the criteria on the records available in that custom view to filter the records further. Note that you cannot export records in the Co-owner, Shared by Me, and Shared to Me views.
- Lookup fields of records in a module using the dot (.) operator.
- Records in the events module as an ICS file.
How does the Bulk Read API work?
Scheduling a bulk read job encompasses the following steps.
- Creating a bulk read job.
- Getting the status of the scheduled job.
- Downloading the result.
We will now see each of these steps in detail.
Step-1: Creating a bulk read job
This involves making a POST API call to schedule a job to fetch records that match certain criteria, along with the required fields.
When this call is successful, the response returns an id. You can use this id to know the status of the job by polling, or check the job completion in the callback URL.
Request URL: {{api-domain}}/crm/bulk/v2/read
Request Method: POST
Consider an example where you want to export records from the Contacts module.
The below query fetches the records that matches one of the three criteria—
- The lead source is Advertisement (or)
- The owner's last name is Boyle (or)
- The phone number of the account associated with the contact contains the numbers 99807.
The fields to be fetched are mentioned in the fields array. To fetch all fields in the module, do not input the fields key.
In this query, Account_Name is the default lookup field in the Contacts module. Owner.last_name returns the last name of the owner of the contact, Account_Name returns the ID and Account_Name.Account_Name returns the name of the account associated with the contact, and Account_Name.Phone returns the phone number of the account associated with the contact.
{ "callback": { "method": "post" }, "query": { "module": "Contacts", "fields": [ "Last_Name", "Owner", "Owner.last_name", "Account_Name.Account_Name", "Account_Name.Phone", "Lead_Source", "Created_Time" ], "criteria": { "group_operator": "or", "group": [ { "api_name": "Lead_Source", "comparator": "equal", "value": "Advertisement" }, { "api_name": "Owner.last_name", "comparator": "equal", "value": "Boyle" }, { "api_name": "Account_Name.Phone", "comparator": "contains", "value": "99807" } ] }, "page": 1 } } |
The below table gives the description of the keys in the sample input.
Key and Data Type | Mandatory | Description |
callback JSON Object | Yes | Contains a valid URL, which should allow the HTTP POST method. The Bulk Read Job's details are posted to this URL on successful completion or failure of the job. |
query JSON Object | Yes | Contains the module, fields that you want to export, criteria based on which you want to export the records, and the page. Refer to the query properties table below for more details. |
file_type String | Yes, when you want to export the events as an ICS file. | Specify the value of this key as "ics" to export all records in the Events module as an ICS file. |
query properties
Key and Data Type | Mandatory | Description |
module String | Yes | The API name of the module from which you want to export the records. Specify the module name as "Events" if you want to export the records in the Events module as an ics file. |
cvid String | Yes, when you want to export records in a custom view | The unique ID of the custom view whose records you want to export. You can obtain the cvid from the Custom View Metadata API. |
fields JSON Array | No | The API Name of the fields you want to export from the module. Example: First_Name, Last_Name, Email, Owner.last_name. Do not input this key when you want to export the records in the Events module as an ICS file. The system throws FIELDS_NOT_SUPPORTED error, otherwise. |
page Integer | No | Default value for page is 1. The page value '1' means that the first 200,000 records matching your query will be exported. If you want to fetch the records from the range of 200,001 to 400,000, then you should mention the page as '2'. The maximum value for this key is 500. |
criteria JSON Object | No | To filter the records you want to export. This JSON object contains the API name of the field, comparator, and a group. Refer to the criteria properties table below for more details. |
criteria properties
Key and Data Type | Mandatory | Description |
api_name String | Yes, if group and group_operator are not specified. | API name of the field you want to compare. Example: First_Name, Last_Name, Owner.last_name etc,. Example: "criteria": { "api_name": "Lead_Source", "comparator": "equal", "value": "Advertisement" } |
value String or JSON array | Yes, if group and group_operator are not specified. | Positive integer values only. |
group_operator String | Yes, if api_name, comparator & value are not specified. | Logical operators. Supported values are and, or. |
group JSON array | Yes, if api_name, comparator & value are not specified. | Array of criteria objects. |
comparator String | Yes, if group and group_operator are not specified. | Specifies the comparator. Example: equal, greater_than. Refer to the comparators table for more details. |
comparators
Data Type | Comparator | Value and Limits |
Number (Integer), Decimal/BigInteger/ Currency/Percent) | equal, not_equal, in, not_in, less_than, less_equal, greater_than, greater_equal | Any number values or ${EMPTY} for empty value. Not more than 19 digits for big integer, allows decimal values for decimal and currency fields. In multi-currency enabled accounts, only home currency value is supported. |
Text (Email, Phone, URL, Picklist, Multi-select, etc) | equal, not_equal, in, not_in, contains, not_contains, starts_with, ends_with | Any text or ${EMPTY} for empty value. Not more than 255 characters. |
Date | equal, not_equal, in, not_in, between, not_between | Any date value in ISO 8601 format or ${EMPTY} for empty value. |
DateTime | equal, not_equal, in, not_in, between, not_between | Any date time value in ISO 8601 format or ${EMPTY} for empty value. Example: 2019-04-01T14:24:04+05:30. Milliseconds are not supported. |
Boolean | equal | true or false. |
Lookup | equal, not_equal, in, not_in | Biginteger value of the lookup, ${EMPTY} for empty value, or use the .(dot) operator to establish a relation between two modules. Example: In the Contacts module, Owner fetches the ID of the Owner, whereas Owner.last_name fetches the last name of the owner. Account_Name fetches the ID of the Account associated with the base module, whereas Account_Name.Phone fetches the phone number of the account associated with the base module. |
Text Area (Multi-line) | Not supported | Not supported |
The response to the sample query is as follows. You can use the id in the details key to check the job status periodically as explained in step-2.
{ "data": [ { "status": "success", "code": "ADDED_SUCCESSFULLY", "message": "Added successfully.", "details": { "id": "3652397000000646004", "operation": "read", "state": "ADDED", "created_by": { "id": "3652397000000186017", "name": "Patricia Boyle" }, "created_time": "2019-04-01T14:24:04+05:30" } } ], "info": {} } |
For more details and examples, refer to the Create Bulk Read Job page of our API guide.
Step-2: Getting the status of the scheduled bulk read job
The bulk read API supports polling and callback.
Polling
You can poll (check the status of the scheduled bulk read job) with the job ID you received in the previous step.
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.
Request URL: {{api-domain}}/crm/bulk/v2/read/{job_id}
Request Method: GET
The response contains the status of the scheduled job as either ADDED, IN PROGRESS, or COMPLETED.
When the job is complete, the response contains the result JSON object with the keys page, count, more_records, and download_url.
You can also find the download_url in the callback response from which you can download the zip file containing the CSV or ICS file.
If the more_records key is true, there are more records you need to export. Simply change the value of the key page in the POST request, and schedule another bulk read job to fetch the next set of records.
The download_url contains the URL to download the CSV file. Follow the instructions in step-3 to download the CSV file.
Here's a sample response to the above query when the job is completed.
{ "data": [ { "id": "3652397000000646004", "operation": "read", "state": "COMPLETED", "result": { "page": 1, "count": 3, "download_url": "/crm/bulk/v2/read/3652397000000646004/result", "per_page": 200000, "more_records": false }, "query": { "fields": [ "Last_Name", "Owner", "Owner.last_name", "Account_Name.Account_Name", "Account_Name.Phone", "Lead_Source", "Created_Time" ], "module": "Contacts", "criteria": { "group_operator": "or", "group": [ { "api_name": "Lead_Source", "comparator": "equal", "value": "Advertisement" }, { "api_name": "Owner.last_name", "comparator": "equal", "value": "Boyle" }, { "api_name": "Account_Name.Phone", "comparator": "contains", "value": "99807" } ] }, "page": 1, "cvid": "554023000000093005" }, "created_by": { "id": "554023000000235011", "name": "Patricia Boyle" }, "created_time": "2019-05-09T14:01:24+05:30" } ] } |
The other possible values for the key state are
- ADDED - Indicates that the job is scheduled.
- IN PROGRESS - Indicates that the job is under processing.
Note that only a completed job will have the download URL in its response.
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.
Below is a sample callback response for a completed job.
{ "job_id": "554023000000568002", "operation": "read", "state": "COMPLETED", "query": { "module": "Contacts", "criteria": { "group": [ { "api_name": "Lead_Source", "comparator": "equal", "value": "Advertisement" }, { "api_name": "Owner.last_name", "comparator": "equal", "value": "Boyle" }, { "api_name": "Account_Name.Phone", "comparator": "contains", "value": "99807" } ], "group_operator": "or" }, "page": 1, "fields": [ "Last_Name", "Owner", "Owner.last_name", "Account_Name.Account_Name", "Account_Name.Phone", "Lead_Source", "Created_Time" ], "cvid": "554023000000093005" }, "result": { "page": 1, "count": 1588, "download_url": "/crm/bulk/v2/read/554023000000568002/result", "per_page": 200000, "more_records": false } } |
For more details, refer to the Get Bulk Read Job Details page of our API guide.
This is the final step to complete exporting records from a module in Zoho CRM.
Make a GET request to the download_url you received in the response of step-2.
Step-3: Downloading the CSV file
Request URL: {{api-domain}}/crm/bulk/v2/read/{job_id}/result
Request Method: GET
This request downloads the zip file. Extract it to get the CSV or ICS file.
Limitations
- Only 10 requests for download are allowed for a one-minute interval. Crossing the limit throws the error with the HTTP code 429. All subsequent downloads will be unsuccessful.
- After completing the bulk read job, you can access the downloadable file only for a period of one day. After that, you cannot access the file via the endpoints.
- You can specify a maximum of 200 select fields via an endpoint. If you specify more than that, the system exports all fields available in that module.
- The maximum value of the page key in the export request body is 500.
- You can specify a maximum of 25 criteria in a query. This also includes the number of criteria in a custom view or a standard view. For example, if you specify the ID of the standard view "My converted Leads", which uses two criteria, the remaining criteria that you can use in the query will be 23.
- in and not_in comparators can accept up to 20 values. For example: 'Lead Status' - 'in' - 'Cold,Warm,Hot,Junk,Contacted,Not Contacted,....(20 values)'.
- You cannot retrieve multi-line, multi-select lookup fields.
- Custom views in the Activities module, Co-Owner view in the Contacts module, the standard views Shared By Me and Shared To Me are not supported in this API.
For more details, refer to the Limitations page of our API guide.
We hope you found this post useful. Let us know your thoughts in the comment section, or reach out to us at support@zohocrm.com if you have any questions.
Cheers!
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
Shylaja S
Parikshit
Praveen Sankar
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
Missed chats on WhatsApp closing after one minute
Hi, we have added WhatsApp as a channel. However, if a chat is not picked up within 2mins, the chat is marked as missed and is closed within a minute. Why are they not staying in our "missed" queue for 24 hours as per our WhatsApp preference settings?Feature Request: Add Tax ID Display on Event Tickets
Hello Backstage Team, I’ve had several clients bring up an issue regarding tax compliance when creating events. For tax purposes, they are required to show their Tax ID on the event tickets. Currently, this isn’t an option, so they have to manually generateRelease Notes | January 2026
We have rolled out a set of powerful new enhancements across Zoho Vertical Studio that bring several long-awaited capabilities to your applications. These updates focus on deeper customization, smarter automation, better reporting, and improved usabilityEmail Alias: To keep emails flowing without disruption
Email Alias acts like a nickname for a user’s primary email address, allowing multiple email addresses to deliver messages into the same mailbox. Consider the scenario where an employee manages multiple responsibilities, such as responding to sales inquiries,Archive Option in Conversation View
Hello, I have a suggestion\request to add an "Archive Thread" button in conversation view of Zoho Mail. The best suggestion I have is to put an "Archive Thread" button next to the "Label Entire Thread" button in conversation view. Most users don't justInventory "Bulk Actions" button - add more fields to "Bulk Update > Select a field"
Can we not get a lot more actions that are commonly used by customers into the "More Actions" button on the Inventory list? More fields listed in the Bulk Update > Select A Field? Possible Bulk update Fields Preferred Supplier ( to quickly move itemsBulk upload image option in Zoho Commerce
I dont know if I am not looking into it properly but is there no option to bulk upload images along with the products? Like after you upload the products, I will have to upload images one by one again? Can someone help me out here? And what should I enterFunction #11: Apply unused credits automatically to invoices
Today, we bring you a custom function that automatically applies unused credits from excess payments, credit notes, and retainer payments to an invoice when it is created. Prerequisites: Create a Connection named "zbooks" to successfully execute the function.Tip #60- Exploring Technician Console: Screen Resolution- 'Insider Insights'
Hello Zoho Assist Community! Have you ever started a remote session and felt the screen quality wasn’t sharp enough for detailed work? A new user recently explored Zoho Assist after installing the trial version and running a few initial tests. While theRight Moment, Right Message, Right Operator: Never Miss a High-Intent Lead
Ever been on a website or app, thinking “Should I buy this or not?” and suddenly a friendly message “Hi! How can I help you?” pops up at the perfect moment? That’s not luck. That’s timing done right. Engaging right visitors at the right moment, with theCRM x WorkDrive: We're rolling out the WorkDrive-powered file storage experience for existing users
Release plan: Gradual rollout to customers without file storage add-ons, in this order: 1. Standalone CRM 2. CRM Plus and Zoho One DCs: All | Editions: All Available now for: - Standalone CRM accounts in Free and Standard editions without file storageZoho CRM Workflow Automation: Activate & Deactivate Workflows Using API
Zoho has now enabled: ✅ Activate / Deactivate workflows using API ✅ Schedule workflow activation & deactivation This is extremely useful for real-world automation use cases 💡 🧩 My Use Case I created a scheduled automation that: ☀️ Activates workflows{Action Required} Re-authenticate your Google Accounts to Continue Data Sync
Hello Users! To align with Google’s latest updates on how apps access files in Google Drive, we’ve enhanced our integration to comply with the updated security and privacy standards, ensuring safer and more reliable access to your data. With this update,Function #53: Transaction Level Profitability for Invoices
Hello everyone, and welcome back to our series! We have previously provided custom functions for calculating the profitability of a quote and a sales order. There may be instances where the invoice may differ from its corresponding quote or sales order.Project-Based Inventory Consumption and Proforma Invoice in Zoho ERP
While working with customers across different industries, we have identified a few functional questions and gaps that commonly arise—especially for project-based and service-oriented businesses. Many organizations, such as those in shipping, construction,[Free Webinar] Zoho RPA - OCR, PDF Automation, & More
Hello Everyone! Greetings from the Zoho RPA Training Team! We’re excited to invite you to our upcoming webinar on the latest release updates for Zoho RPA, where we’ll unveil powerful new capabilities designed to make your automation journey smarter, faster,Zobot Execution Logs & Run History (Similar to Zoho Flow)
Dear Zoho SalesIQ Team, We would like to request an enhancement for Zoho SalesIQ Zobot: adding an execution log / run history, similar to what already exists in Zoho Flow. Reference: Zoho Flow In Zoho Flow, every execution is recorded in the History tab,Global Search Settings
I'd love a way to remove some modules from being included in the global search. This would allow use to provide a better user experience, limiting the global search to only those modules that are regularly used removing any models used for backgroundCard Location in Zobot
Hello, when using the “Location” card in a codeless builder Zobot, the behavior in WhatsApp is inconsistent. When asking the user to share their location, they can type a message, which will return the message “Sorry, the entered location is invalid.Automation Series: Auto-create Dependent Task on Status Change
In Zoho Projects, you can automatically create and assign a dependent task when a task’s status is updated. This helps teams stay aligned, ensures reviews happen on time, and reduces manual effort. In this post, we’ll walk through an easy setup usingLanguages in Zobot
Hello, I have found a list of supported languages for the Zobot. The information specifies the languages are supported in the following 3 features: SalesIQ supports 34 different languages in the following features. Resources (Articles, FAQs, Small Talks)Composite items inside of composite items; bill of materials needed
Hi Zoho and Everyone, I am evaluating whether Zoho Inventory will work for my small business. I grow and harvest herbs and spices but also get from wholesalers. I use all these items to make herbal teas, but also sell them as individual items on my Shopify store and Etsy. I discovered the composite item bundling and am wondering if I could get some assistance since there is no bill of materials: Our herbal company's best selling tea is a sleepytime tea. Sleepytime Tea can be purchased in three weightsAction required: Reauthorizing your Google account in Zoho Sign for automatic cloud backup to Google Drive
This is applicable to users who have already configured automatic cloud backup to Google Drive. Hi there! Google has mandated reauthorization of all preconfigured third-party integrations to ensure only the necessary scopes are shared as an improved securityZoho CRM Layouts
I have customised all our modules, Leads, Contacts and deals, and within them, I have created lots of different layouts depending on the type of Lead or contact, for example. Since the new Zoho UI came out, they have all disappeared. I have gone intoStreamlining E-commerce Photography with AI Background Tools
Hey Zoho Community, I’ve been messing around with ways to make product images less of a headache for fashion brands on Zoho Commerce. You know how boring generic backdrops can get, and how much time traditional photoshoots eat up, right? I tried out thisWhatsApp IM in Zoho Desk always routes to Admin instead of assigned agent
Hello Zoho Experts, I connected WhatsApp IM to my Zoho Desk account. I only assigned my Customer Service (CS) agent to the WhatsApp channel, and I did NOT include Admin in this channel. However, every new WhatsApp conversation automatically gets assignedhide resolution from help centre
to my surprise, i just found out that the resolution text is public in the helpcenter, even if 'notify customer' is off. is there a workaround to that? how do others deal with this? How zoho support does this and I don't think its used by Zoho in the first place. the resolution is meant to be private, not publicZoho Analytics + Facebook Ads: Performance Alerts for Active Campaigns
Is it possible with integration of Zoho Analytics with Facebook Ads and set up alerts or notifications for active campaigns when performance drops? For example, triggering a notification if CTR goes below a defined threshold or if other key metrics (likeMultiple upload field CRM
I desperately need the functionality to add more than one upload field to web to contacts form. How can I do this?Sort by age
It would be very helpful if there was a way to sort by age in the Age column. Please add this function if possible. Thanks!Lookup Field Option Not Available in Customization
Hello, I am trying to customize different modules (e.g., Work Orders, Systems, and others), but I am unable to find the Lookup field option in the layout customization. When I go to: Setup → Customization → Modules and Fields → Add Field The Lookup fieldScheduled sending of a poll and its results
Is there a way to schedule sending a poll to all my users and have the results sent separately to the team?Canvas View bug
I would like to report a bug. When clone a canvas view from an existing canvas view, if the original canvas view have canvas button with client script. Then the new create canvas view will have canvas button, it is make sense. But when I try to deleteIntegrating Zoho Suite and apps more with Linux
I just got introduced with Zoho just couple of months ago, and I've already planned to contribute to it, even though it's not an open-source software. Still I have found it's potential to beat the tech giants and still being respective towards data privacyStore Submitted Forms as PDF
Hi there, Is there a method to store Form submissions as a PDF in workdrive for archival? I set the form to email the submission to the user and an internal inbox but I'd really love to store the final form as PDF in workdrive automatically. I can't seemSystem Components menu not available for Tablet to select language
I have attached a screenshot of my desktop, mobile, and tablet menu builder options. I am using 2 languages in my application. Language Selection is an option under the System Components part of the menu, but only for my desktop and phone(mobile). MySeparate Items & Services
Hi, please separate items and services into different categories. Thank youCRM->INVENTORY, sync products as composite items
We have a product team working in the CRM, as it’s more convenient than using Books or Inventory—especially with features like Blueprints being available. Once a product reaches a certain stage, it needs to become visible in Inventory. To achieve this,Add an option to disable ZIA suggestions
Currently, ZIA in Zoho Inventory automatically provides suggestions, such as sending order confirmation emails. However, there is no way to disable this feature. In our case, orders are automatically created by customers, and we’ve built a custom workflowWhat's new in Zoho Sheet: Simplify data entry and collaboration
Hello, Zoho Sheet community! Last year, our team was focused on research and development so we could deliver updates that enhance your spreadsheet experience. This year, we’re excited to deliver those enhancements—but we'll be rolling them out incrementallyNext Page