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
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
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! CommandsKaizen #165 : How to call Zoho CRM APIs using Client Script
Welcome back to another exciting Client Script post! In this post, we will discuss one of the most frequently asked questions: How do you call Zoho CRM APIs from Client Scripts? In this kaizen post, 1. Ways to make calls to Zoho CRM APIs using ClientKaizen#162 : Add Tags and Open Pre-filled Email Drafts via Client Scripts
Hello everyone! Welcome to another informative Kaizen post. In this post, let us see how to accomplish the following using Client Script. 1. How to auto-tag a record based on field update? 2. How to Open a pre-filled email draft This post will provideExtension Pointers - JS SDK series #4: Managing data from a widget using ZOHO.CRM.HTTP
Handling and managing the data between two applications is a major factor for an efficient business. There are a variety of ways to handle data between Zoho CRM and other third-party applications. You can use deluge CRM tasks, create connectors, use APIKaizen #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 achieved
New to Zoho TeamInbox?
Zoho TeamInbox Resources
Zoho DataPrep Resources
Zoho CRM Plus Resources
Zoho Books Resources
Zoho Subscriptions Resources
Zoho Projects Resources
Zoho Sprints Resources
Qntrl Resources
Zoho Creator Resources
Zoho Campaigns 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
Blueprint: multi-select lookup field not available in the criteria option
I read this old forum post which stated that multi-select lookup fields are now selectable as an option in a Blueprint transition configuration: https://help.zoho.com/portal/en/community/topic/blueprint-multi-select-lookup-field-not-available-within-blueprint-transitionApply Credit Note Automatically
We need the ability to apply open Credit Notes toward invoices generated by recurring invoice as the first, priority payment. This should be an option that we can enable/disable in the recurring profile and/or the Credit Note. Other invoicing systems can do this. I'm not sure why Zoho Invoice doesn't have it. Here's an example for a Recurring Invoice... If a customer has open Credit Notes, and a saved credit card set for auto-pay, once an invoice goes out, the credit balance gets automatically appliedWorkflow for "Expenses" module?
Hi there, over the last 2 years, Zoho Expense has seen tremendous growth and we are happy with it. But, sometimes it is frustrating to see things are being implemented halfheartedly, or so it seems. For example, There is the possibility to create workflowsRecord Template - Conditionally printing sections
Is there a way to conditionally print a section of a Record Template? More specifically I am printing records from a Form "Invoice". That Form has 3 SubForms. I'd like to print the content of those SubForms using a Record Template but only if they have at least one line item. If they have no line items, I'd like to hide the headers for that section on the printout.User can choose the PDF report
Hi. I would like to find out if a user (Creator or customer portal) to choose from the different PDF customised reports that have been built?Query table pull last 12 months
I am tying to pull the following criteria and the date is always what causes me the issue. I want to pull people (pco_id) who have entries of "event_id" being these 2 events and whos "kind" is Regular or Guest and where the event_starts_at (date column)PLEASE FIX Search options and consider a Global seach option
A recent update has removed the ability to search for addresses and phone numbers under contacts. We cannot find where this moved to (If it is still available). Please put these options back as we cannot locate specific projects anymore. Also please consider allowing for a Global search. This would really improve the search engine. For example: If I search for "Sally Jones" then all invoices , estimates, vendors etc.. would populate.. Please let me know if you need any more information. Thank You....Customize your calendar based on personal preferences
Greetings, We're happy to introduce a few new capabilities to the Activities module's Calendar View! Now you can tailor your calendar's appearance and notification settings to suit your needs. In the past, the Calendar View lacked customization optionsBUG ALERT: Client Script + Commands -> $Page contextual data is not updated
When using the new Client Script Commands feature, there is an issue with the Client Script $Page contextual data not accurately being updated each time a Command is run. Assuming a Client Script Command called "Client Script Command Bug" with the followingShow iFrame of related List inside of Blueprint Transition
Hey, is it possible to show an iFrame of a related list like this inside of a Blueprint transition?Lookup Fields not Converting
I manage holiday properties. I have a lookup to the Accounts (Properties) in the Leads module. The lookup is connected to the property address field. When I convert it the lookup field does not update in Deals, although the property address does. There2024: A Year of Transformation with Zoho Forms
As we close the curtain on another exciting year, it’s time to reflect on the strides Zoho Forms has taken in 2024. From empowering businesses with advanced tools to simplifying workflows and enhancing user experiences, our updates this year were allStop selling out of stock Items.
Hi I have been using Zohobooks for a around 8 month now. I am not involved in selling process but my staff cant stop selling product which they do not hold in stock, this is a big headache for me as physical count never matches what is shown on the books.Bigin API Token Request ("invalid_client")
Hi people, I tried to connect to the API without success, I've read all of the documentation multiple time and tried just about everything. I tried to do it with Python Request module and with Postman, passing the information through both the URL parameterCustomer Happiness not clickable when using API
Is there a way to automatically add the Customer Feedback links when generating email drafts via the API? Currently, the feedback links are only added when generating an email draft using the UI. I tried using the endpoint described in https://desk.zoho.com/DeskAPIDocument#CustomerFeedback#CustomerFeedback_GetthecustomerfeedbackplaceholderlinkSend To Zoho Sign not Showing
The button send to Zoho sign is not showing on my Zoho CRM . Is there additional steps I need to take after installing Zoho Sign to CRM ?How to Get An Image's URL once it's uploaded to library?
I manage to find URLs to the images I uploaded to my library, but after a day, it seems the links stop working like its only temporary. Where can I find the ACTUAL solid URL for my images that I upload to my Library so I can use them for my custom template / HTML coded template? Thanks, Mac【Zoho CRM】インポート機能のアップデート：既存データへのタグ追加が可能に！
ユーザーの皆さま、こんにちは。コミュニティチームの藤澤です。 今回は「Zoho CRM アップデート情報」の中のインポート機能のアップデートをご紹介します。 Zoho CRMのタグは、データを効率的に分類、認識するためのラベルです。 タグ付けは次の3つの方法で行えます： 個別タグ付け：少数のデータを手動でタグ付け 自動化：特定のタイミングで繰り返しタグ付け 一括更新：インポート機能でタグを追加または更新 今回のアップデートでは、インポート時に既存のタグを残したまま、新しいタグの追加、既存タグを置き換えできるようになりました。Link to Desk tickets
Hello, We are using Analytics to analyze data in Desk. Is there a way to embed a link to a ticket in reports? We'd love to be able to see the drill down data, and click a value in a result row that would launch the Desk Ticket in another window/tab. Thanks in advance for any ideas!Bluerprints: How to connect the created record back?
I've a blueprint which creates another record as part of an 'After' transition. But the two records don't seem to be linked together. If it's not automatic - how do I get the created record ID to link it to the original record? Thanks!Populate a Related List Item based on a Stage
I would like to know if I can populate a CLOSED DEAL section in a contact that populates only when a Deal (something in the Deal Module) is listed as Closed - Won. I'd like another section that is just called deals, which shows me all other deals thatBeing able to draw inside a module ?
I was wondering if anyone know of a solution for this request. We would like to be able to draw directly from one module in the CRM and have it attached to that record. Here is an example. Paul would go to the customer once he as done the measuring, he2 serial numbers for 1 item (Mac address and Serial number)
There is a way to track 2 serial number type for 1 Item. Ex: Some electronic devices have a MAC address and a serial number. I need to track those 2 numbersHolidays
Hi; For defining Holidays, you need to add logic to handle the year as well as the month & day. We need to be able to enter Holidays for the next year. I need to add a holiday for January 2, 2017, but I can't until January 1st, which is a Sunday and weDelete a department or category
How do I delete a Department? Also, how do I delete a Category? This is pretty basic stuff here and it's impossible to find.Remove or hide default views
I'm looking to only have the views pertinent to my organization. Is there a way to show only my custom views (or separate them to a different area or something)? If not, this should be a feature as switching from Zendesk we had this option...Analytics Module: Can you move items from one dashboard to another?
Is there a way to move items from one dashboard to another? I want to rearrange my dashboard now that I know what i'm doing but i don't want to remake my various widgets? Edit: Hey Zoho, This would be a good feature: to be able to move/copy widgets toCopy Widget to another Dashboard
I can see the option to clone a widget to the same dashboard but is it possible to copy it to another dashboard?Is there a way to print the dashboard?
I would like the capability of printing the dashboard - is that possible?Custom Deal Name in Lead Conversion Mapping
I know there are ways to change the name of a Deal after conversion using a custom function, so no need to repost that information. I would like to see the CRM Improved with Deal Name Customisation and I think the Lead Conversion Mapping page would beIntroducing Record Summary: smarter insights at your fingertips
Hello everyone, Building on the recent launch of Zoho's in-house Zia Large Language Model (Zia LLM)—a major milestone in Zoho CRM’s AI capabilities—we’re excited to introduce the Record Summary feature. This powerful addition makes use of Zia LLM to simplifySuppress "spreadsheet will not be saved" message on published sheet
I have published a sheet and have one column on that sheet that the user can edit (a dropdown picklist where the user can select the status for each line). Is there a way to suppress the Zoho Sheet message "Any changes made to this published spreadsheetMissing "Email Authentication" tab
Backstage is alerting users about "Unauthenticated Domains" with a large prompt in the backend. It adds a link to learn more. On this tutorial page, it shows where to find the "Email Authentication" tab in this screenshot. However, in our Backstage, thatShow item Cost value on Item screen
The Item screen shows Accounting Stock and Physical Stock. It would be very helpful if value information could be displayed here as well, for instance Cost Price. Currently, to find the Cost Price (as used for inventory valuations) from inside the itemZoho Analytics to Zoho Sheets - automatic update?
Hi all, If I create a zoho sheet from an Analytics Report or Analytics Data, is there a way for the zoho sheet to automatically update as the Report / Data in analytics updates?Integration with Moodle
Greetings, I hope find all doing well and safe. I've recently returned to using Zoho Flow after a break and was hoping to connect my WooCommerce store with Moodle, the world's most widely used learning management system. My goal was to automatically enrollHow to Record Loan with interest
I have received loans from friend he give me like 2 loans so far one is one year repayment and one short, how to properly record his payment, and repayment and give him statement for each loan he give meTask status - completed - other options
I have a dumb question I know i can make custom statuses for the tasks - but is there anyway to make additional "completed" statuses like for instance if i have a task "call back customer" and i leave a vm for them to call back marking it "completed -Task module and related-to field
In modules other than the Task Module I can add several lookup fields to provide a variety of relationships. In the Task module lookup fields are not available. There is only one "related to" field which I want to use for Company. But I want to relateAdd Lookup Field in Tasks Module
Hello, I have a need to add a Lookup field in addition to the ones that are already there in the Tasks module. I've seen this thread and so understand that the reason lookup fields may not be part of it is that there are already links to the tables (https://help.zoho.com/portal/en/community/topic/custom-fields-on-task-module).Next Page