Zoho: Create a bulk write job

← Bulk write operations · Get started

Operation zoho.createbulkwritejob

Provider route: POST /crm/bulk/v8/write. 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["bulkWrite"]["createBulkWriteJob"]>[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.bulkWrite.createBulkWriteJob(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_write.create_bulk_write_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	Defines the payload for creating a bulk write job, including the operation type, optional callback configuration, and the list of resource configurations. Additional keys: not allowed
body.callback	object	Optional	Specify the callback configuration that Zoho CRM uses to notify your endpoint when the bulk write job completes or fails. Additional keys: not allowed
body.callback.method	string	Required within parent	Specify the HTTP method that Zoho CRM uses to invoke the callback URL. Possible values: post - Sends the job completion notification as an HTTP POST request. One of: post
body.callback.url	string	Required within parent	Specify the URL that receives the job completion notification. The URL must accept the HTTP POST method and be reachable from Zoho CRM servers. Format: uri
body.character_encoding	string or null	Optional	Specify the character encoding of the uploaded file. Zoho CRM auto-detects the encoding when this value is omitted; supply a value to override auto-detection and force the file to be read with the specified charset. Maximum length: 50
body.operation	string	Required within parent	Specify the type of bulk write operation to perform on the file. Possible values: insert - Creates the records from the file as new records in the target module. update - Updates existing records in the target module without creating new ones. upsert - Updates existing records and creates new records that do not exist already. One of: insert, update, upsert
body.resource	array	Required within parent	Specify the list of resource configurations to process in the bulk write job. Each entry describes the target module, the uploaded file to read, and the field mappings to apply. Maximum items: 100
body.resource[]	object	Each item	Specify the configuration for a single bulk write resource, including the target module, the uploaded file ID, the matching key, and the field mappings to apply when the job runs. Additional keys: not allowed
body.resource[].field_mappings	array	Optional	Specify the mapping between columns in the uploaded file and fields on the target module. When omitted, Zoho CRM auto-maps columns to fields whose API names match the CSV header. Maximum items: 500
body.resource[].field_mappings[]	object	Each item	Specify the mapping between a single column in the uploaded file and a field on the target module. Additional keys: not allowed
body.resource[].field_mappings[].api_name	string	Required within parent	Specify the API name of the field on the target module to populate with the column value. Refer to the [Fields API](fields.yaml#$.paths./settings/fields.get) resource for valid values. Maximum length: 100
body.resource[].field_mappings[].index	integer	Required within parent	Specify the zero-based column index in the uploaded file whose value populates the mapped field. Format: int32
body.resource[].file_id	string	Required within parent	Specify the identifier of the previously uploaded file that the bulk write job must read. Obtain this value from the response of the bulk upload file API. Maximum length: 100
body.resource[].file_names	array	Required within parent	Specify the names of the files inside the uploaded archive that the bulk write job must process. Maximum items: 10
body.resource[].file_names[]	string	Each item	Represents the name of a single file inside the uploaded archive that the bulk write job processes. Maximum length: 255
body.resource[].find_by	string	Required within parent	Specify the field that the bulk write job uses to locate existing records when performing an update or upsert operation. Possible values: id - Matches records by their unique record ID in the target module. One of: id
body.resource[].ignore_empty	boolean	Optional	Specify whether to skip empty cells in the uploaded file when updating records. Possible values: true - Ignores empty values in a column and updates only the fields that carry a non-empty value. false - Updates the target field with the empty value supplied in the file.
body.resource[].module	object	Required within parent	Specify the target CRM module into which the records from the uploaded file are written. Additional keys: not allowed
body.resource[].module.api_name	string	Required within parent	Specify the API name of the target CRM module into which records are imported. Refer to the [Get Modules](modules.yaml#$.paths./settings/modules.get) resource for valid values. Maximum length: 100
body.resource[].type	string	Required within parent	Specify the type of the resource being imported. Possible values: data - Indicates that the resource contains record data to be written into the target module. One of: data

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 success envelope that Zoho CRM returns after scheduling a bulk write job. Contains the overall status, response code, message, and the details of the newly scheduled job. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned for the bulk write job creation. Possible values: SUCCESS - Indicates that the bulk write job was scheduled successfully. FILE_UPLOAD_SUCCESS - Indicates that the file associated with the job was uploaded successfully. Known values: SUCCESS, FILE_UPLOAD_SUCCESS
details	object	Required within parent	Represents the details of the newly scheduled bulk write job. Additional keys: not allowed
details.created_by	object	Required within parent	Represents the Zoho CRM user who created the bulk write job. Additional keys: not allowed
details.created_by.id	string	Required within parent	Represents the unique identifier of the Zoho CRM user who created the bulk write job. Refer to the [Users API](users.yaml#$.paths./users.get) endpoint for details. Maximum length: 100
details.created_by.name	string	Optional	Represents the display name of the Zoho CRM user who created the bulk write job. Refer to the [Users API](users.yaml#$.paths./users.get) endpoint for details. Maximum length: 100
details.id	string	Required within parent	Represents the unique identifier of the newly scheduled bulk write job. Use this value to query the job status through the get job details operation. Maximum length: 100
message	string	Required within parent	Represents the response message for the bulk write job creation. Possible values: success - Confirms that Zoho CRM scheduled the bulk write job. file uploaded - Confirms that Zoho CRM accepted the uploaded file for the job. Known values: success, file uploaded.
status	string	Required within parent	Represents the overall status of the bulk write job creation request. Possible values: success - Indicates that Zoho CRM scheduled the bulk write job successfully. Known values: success

Policy, approvals and errors

SDK function policy ID: zoho.createbulkwritejob. Catalog operation: createBulkWriteJob. 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