Create Bulk Read job (Bulk Export)
Table of Contents
Purpose
To create a bulk read job to export records.
Request Details
Request URL
https://<base_url>/api/bulk/v2/<account_owner_name>/<app_link_name>/report/<report_link_name>/read
Request method
POST
Header
| Key | Value | Description |
| Authorization | Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf | An authentication token (authtoken) allows users to access apps and APIs without having to enter their login credentials each time. |
Scope
scope=ZohoCreator.bulk.CREATE
where,
| base_url | Zoho Creator: The base URL of your Creator account For example, it's creator.zoho.com if your account belongs to Zoho's US DC, and is creator.zoho.eu if it belongs to Zoho's EU DC. Zoho Creator On-premise: The base URL specific to your Zoho Creator On-premise account. This URL will be either https://host_name:port_number (learn more) or the hostname of the server where Creator On-prem is running. |
| account_owner_name | the username of the Creator account's owner |
| app_link_name | the link name of the target application |
| report_link_name | the link name of the target report |
| read | name of the operation performed |
Request method
POST
Request JSON (optional)
- queryJSON Object
(Optional) Represents the JSON object that holds the keys and their value that form the criteria for bulk export. The following are the keys in the JSON object:
- fields (JSON array, optional) -
Represents the API name of the fields that you want to export. For instance, Email, Single_line, Number and so on. - criteria (string, optional) -
(Optional) The criteria using which you want the API request to filter the target report. Refer to the section below to learn more about defining the criteria. - max_records (Integer) - Represents the number of records to be fetched in one batch
- record_cursor - Token will be valid for a period of 15mins. Request for a further fetch of request with this particular cursor should reach the server within 15mins.
Note
- When you’re fetching batches of records and have reached the last batch, the record_cursor will not be received in the last batch. For example, consider you are fetching five hundred thousand records in two batches of two hundred thousand records and one batch of one hundred thousand records (last batch), the record_cursor will not be received in the last batch of one hundred thousand records.
Defining the Search Criteria
- The search criteria is a combination of one or more expressions. An expression is defined using a field, operator, and value.
- An expression can use all field types except section and add notes. The field's data type dictates the operator that can be used and the format in which the value is to be given.
- You can use logical operators && (AND) and || (OR) to link the expressions in your criteria. These operators are subject to precedence, which you can manage using parentheses ().
- Values for STRING type fields, such as single line, email, and phone, must be enclosed in double-quotes.
- Values for the time, date, and date-time fields must adhere to the application's date and time formats and must be enclosed in single-quotes.
- The record ID must be passed when you want to filter the records using the lookup and integration fields.
- When using the multi select, checkbox or multi-select lookup fields, you can specify only one value per expression.
| Sample value for the parameter "criteria" | Description |
|---|---|
| Name.last_name == "Boyle" | To fetch the records where the last name is Boyle |
| Name.last_name != "" | To fetch the records where the last name is not empty |
| Name.first_name.startsWith("Pat") | To fetch the records where the first name starts with "pat", such as Patricia and Patrick |
| Email_Address.endsWith("zylker.com") | To fetch the records where the email address ends with zylker.com |
| Feedback.contains("it's awesome") | To fetch the records where the feedback (a multi line field) contains the phrase "it's awesome" |
| Total = 250.00 | To fetch the records where the total (a currency field) is equal to 250.00 |
| Total >= 100.00 | To fetch the records where the total (a currency field) is greater than or equal to 100.00 |
| Total < 50 | To fetch the records where the total (a decimal field) is less than 50 |
| Appointment_Date = '13-Apr-2020' | To fetch the records where the appointment date (a date field) is 13-Apr-2020 (as per the application's date format) |
| Appointment_Date >= '13-Apr-2020' && Appointment_Date <= '18-Apr-2020' | To fetch the records where the appointment date (a date field) ranges from 13-Apr-2020 to 18-Apr-2020 |
| Order_Status=="Open" || Order_Status=="In-progress" | To fetch the records where the order status (a drop down or radio field) is either Open or In-progress |
| Status == "Open" && Total > 250.00 | To fetch the records where the status (a drop down field) is Open and Total (a currency field) is greater than 250.00 |
| Product = 3888832000000113058 | To fetch the records where the product (a single-select lookup field) equals 3888832000000113058 (ID of a record present in the looked-up form) |
| Expedited_Delivery=false | To fetch the records where the expedited delivery (a decision box field) is false |
| Hobbies.contains("Reading") | To fetch the records where the hobbies (a multi select or checkbox field) includes reading |
| Hobbies="Reading" && Hobbies="Hiking" | To fetch the records where the hobbies (a multi select or checkbox field) are reading and hiking |
- operation (string)-
Specifies the type of action the API completed. Sample - "operation" : "read”. - created_by (string)-
Specifies the name of the user who initiated the bulk read job. Sample - "created_by": "jason18", - created_time (string)-
Specifies the created time of the bulk read job. - status (string)-
Specifies the current status of the bulk read job. Example: "state": "IN PROGRESS", "COMPLETED", or "FAILED". - id (string)-
Specifies the unique identifier of the bulk read job. Use this ID to check the job status and download the result. Sample - "id": "2000000018003".
Note
- A maximum of two hundred thousand records can be exported in a single export job. To know more about the Bulk API limits, refer this page.
- If the "fields" attribute is not passed (or left empty) in the query JSON, all the fields available for the quick view of the corresponding report are listed in the CSV file. If you only need specific fields, specify the field API names for export.
Sample Request schedule job for report ( with default values and no body)
Copied
Sample request for scheduling a bulk read job (optional)
Copied
Sample Response:
Copied