Zoho: Create a bulk read job

← Bulk read operations · Get started

Operation zoho.createbulkreadjob

Provider route: POST /crm/bulk/v8/read. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/zoho with npm, or alter-sdk-zoho with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { ZohoIntegration } from "@alter-ai/zoho";

async function execute(input: Parameters<ZohoIntegration["bulkRead"]["createBulkReadJob"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new ZohoIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.bulkRead.createBulkReadJob(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_zoho import ZohoIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = ZohoIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.bulk_read.create_bulk_read_job(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	object	Required within parent	Represents the request payload used to configure and create a bulk read job in Zoho CRM. Additional keys: not allowed
body.callback	object	Optional	Specify the callback configuration to receive a POST notification when the bulk read job completes or fails. Additional keys: not allowed
body.callback.method	string	Required within parent	Specify the HTTP method for the callback request. Possible values: post - Sends the callback notification as an HTTP POST request. One of: post
body.callback.url	string	Required within parent	Specify a valid URL that accepts HTTP POST requests to receive the bulk read job completion notification. Format: uri
body.file_type	string	Optional	Specify the file format for the exported records. Possible values: csv - Exports records in CSV format. ics - Exports records in ICS format, applicable only when exporting from the Events module. One of: csv, ics
body.query	object	Required within parent	Specify the query parameters for the bulk read job, including the target module, optional field selection, optional Custom View, and optional filter criteria. Additional keys: not allowed
body.query.criteria	object	Optional	Specify the filter criteria to narrow down the records exported in the bulk read job. Additional keys: not allowed
body.query.criteria.group	array	Required within parent	Specify the list of filter conditions to apply to the bulk read export. Each condition must include a field, value, and comparator. Maximum items: 1000
body.query.criteria.group[]	object	Each item	Specify a filter condition object that defines a single criterion for filtering records in the bulk read export. Additional keys: not allowed
body.query.criteria.group[].comparator	string	Required within parent	Specify the comparison operator to apply between the field and value in this filter condition. Possible values: equal - Records where the field value exactly matches the specified value. not_equal - Records where the field value does not match the specified value. contains - Records where the field value contains the specified value. not_contains - Records where the field value does not contain the specified value. starts_with - Records where the field value starts with the specified value. ends_with - Records where the field value ends with the specified value. One of: equal, contains, ends_with, not_contains, not_equal, starts_with
body.query.criteria.group[].field	object	Required within parent	Specify the field to apply the filter condition on. Refer to the [Get Fields](fields.json#$.paths./settings/fields.get) resource for valid values. Additional keys: not allowed
body.query.criteria.group[].field.api_name	string	Required within parent	Specify the API name of the field to use in the filter condition. Maximum length: 255
body.query.criteria.group[].type	string	Optional	Specify the type of the filter condition. Possible values: value - Compares the field against a static value. One of: value
body.query.criteria.group[].value	string	Required within parent	Specify the value to compare the field against in this filter condition. Maximum length: 500
body.query.criteria.group_operator	string	Required within parent	Specify the logical operator to combine the filter conditions in the group array. Possible values: and - All conditions must be satisfied. or - At least one condition must be satisfied. One of: or, and
body.query.cvid	string or null	Optional	Represents the unique ID of the Custom View to filter records for the bulk read job. Refer to the [Get Custom Views](custom_views.json#$.paths./settings/custom_views.get) resource for valid values. Maximum length: 100
body.query.fields	array	Optional	Specify the list of field API names to include in the exported records. Refer to the [Get Fields](fields.json#$.paths./settings/fields.get) resource for valid values. Note: If exporting Events as an ICS file, do not include this key. Maximum items: 1000
body.query.fields[]	string	Each item	Specify the API name of a field to include in the exported records. Maximum length: 500
body.query.module	object	Required within parent	Specify the CRM module from which to export records. Refer to the [Get Modules](modules.json#$.paths./settings/modules.get) resource for valid values. Additional keys: not allowed
body.query.module.api_name	string	Required within parent	Specify the API name of the CRM module to export records from. Maximum length: 255
body.query.page	integer or null	Optional	Specify the page number of records to export in the bulk read job. The default value is 1 and means that the first 200,000 records matching your query will get exported. If you want to fetch the records from the range 200,001 to 400,000, then mention the value as ‘2’. Format: int32

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	object	Root	Represents the response returned when a bulk read job is successfully created. Additional keys: not allowed
data	array	Required within parent	Represents the list of job creation result objects. Maximum items: 1000
data[]	object	Each item	Represents a single job creation result object. Additional keys: not allowed
data[].code	string	Required within parent	Represents the status code for the job creation result. Possible values: ADDED_SUCCESSFULLY - Zoho CRM created the bulk read job successfully. Known values: ADDED_SUCCESSFULLY
data[].details	object	Required within parent	Represents the details of the newly created bulk read job. Additional keys: not allowed
data[].details.created_by	object	Required within parent	Represents the user who created the bulk read job. Refer to the [Get Users](users.json#$.paths./users.get) endpoint for details. Additional keys: not allowed
data[].details.created_by.id	string	Required within parent	Represents the unique ID of the user who created the bulk read job. Maximum length: 100
data[].details.created_by.name	string	Optional	Represents the name of the user who created the bulk read job. Maximum length: 256
data[].details.created_time	string	Required within parent	Represents the date and time when Zoho CRM created the bulk read job. Format: date-time
data[].details.id	string	Required within parent	Represents the unique ID of the created bulk read job. Maximum length: 100
data[].details.operation	string	Required within parent	Represents the type of bulk operation performed. Possible values: read - Indicates a bulk read (export) operation. Known values: read Maximum length: 500
data[].details.state	string	Required within parent	Represents the current state of the bulk read job. Possible values: ADDED - The job has been accepted and is queued for processing. IN PROGRESS - The job is currently being processed. COMPLETED - The job has finished processing successfully. FAILURE - The job encountered an error during processing. Known values: COMPLETED, ADDED, IN PROGRESS, FAILURE
data[].message	string	Required within parent	Represents the result message for the job creation. Possible values: Added successfully. - Zoho CRM created the bulk read job successfully. Known values: Added successfully.
data[].status	string	Required within parent	Represents the status of the job creation request. Possible values: success - Zoho CRM created the bulk read job successfully. Known values: success
info	object	Required within parent	Represents additional metadata about the bulk read job creation response. Additional keys: not allowed

Policy, approvals and errors

SDK function policy ID: zoho.createbulkreadjob. Catalog operation: createBulkReadJob. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source