Zoho: Submit mass convert job for leads

← Mass convert operations · Get started

Operation zoho.massconvert

Provider route: POST /crm/v8/Leads/actions/mass_convert. 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["massConvert"]["massConvert"]>[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.massConvert.massConvert(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.mass_convert.mass_convert(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 for a mass convert operation, containing the lead IDs to convert and optional configuration fields. Additional keys: not allowed
body.Deals	object	Optional	Must contain the mandatory keys “Deal_Name”, “Stage”, “Closing_Date”, and “Pipeline”(if enabled), besides the other mandatory fields configured for the Deals module. Note that if there are layouts other than Standard, the custom-defined mandatory fields will not be processed while converting the lead. Additional keys: not allowed
body.Deals.Deal_Name	string	Required within parent	Specify the name of the deal to create for the converted lead. Maximum length: 255
body.apply_assignment_threshold	boolean	Optional	Specify whether assignment threshold rules should be applied when assigning the converted records. Possible values: true - Apply assignment threshold rules (default). false - Skip assignment threshold rules.
body.assign_to	object	Optional	Specify the user to assign the converted records to. Refer to the [Get Users](users.yaml#$.paths./users.get) resource for valid values. Additional keys: not allowed
body.assign_to.id	string	Required within parent	Specify the ID of the user to assign the converted records to. Refer to the [Get Users](users.yaml#$.paths./users.get) resource for valid values. Maximum length: 255
body.carry_over_tags	array	Optional	The name and ID of the module you want to associate the tags to while converting the lead. For example, if you give contacts in this array, the tags of the lead will be carried over to the contact that the lead is converted to. Use the [Get Modules API](modules.yaml#$.paths./settings/modules.get) to get the ID of the module. Note that you can carry over tags to Contacts, Deals, and Accounts. Maximum items: 3
body.carry_over_tags[]	object	Each item	Each object specifies the module API name and ID for each tag to carry over to the converted record. Additional keys: not allowed
body.carry_over_tags[].api_name	string	Required within parent	Specify the API name of the module to carry the tags over to. Refer to the [Get Modules](modules.yaml#$.paths./settings/modules.get) resource for valid values. Maximum length: 100
body.carry_over_tags[].id	string	Required within parent	Specify the ID of the module to carry the tags over to. Refer to the [Get Modules](modules.yaml#$.paths./settings/modules.get) resource for valid values. Format: int64 Maximum length: 255
body.ids	array	Required within parent	The record IDs of the leads you want to convert. Use the [Get Records API](record.yaml#$.paths./{module}.get) to get the record IDs. Note that you can give a maximum of up to 50 records IDs in this array. Maximum items: 50
body.ids[]	string	Each item	Each object specifies a lead record ID to include in the mass convert job. Maximum length: 255
body.move_attachments_to	object	Optional	The name and ID of the module you want to move the attachments of the lead to after converting. Use the Modules API to get the ID of the module. Note that you can move the attachments to either Contacts, Deals, or Accounts. Additional keys: not allowed
body.move_attachments_to.api_name	string	Required within parent	Specify the API name of the module to move the lead’s attachments to. Refer to the [Get Modules](modules.yaml#$.paths./settings/modules.get) resource for valid values. Maximum length: 100
body.move_attachments_to.id	string	Required within parent	Specify the ID of the target module to move the lead’s attachments to. Format: int64 Maximum length: 255
body.portal_user_type	object	Optional	Specify the portal user type for the contact created from the converted lead. Refer to the [Get Portal User Types](portal_user_type.yaml#$.paths./settings/portals/{portal}/user_type/users.get) resource for valid values. Additional keys: not allowed
body.portal_user_type.id	string	Required within parent	Specify the ID of the portal user type to assign to the converted contact. Refer to the [Get Portal User Types](portal_user_type.yaml#$.paths./settings/portals/{portal}/user_type/users.get) resource for valid values. Format: int64 Maximum length: 255
body.related_modules	array	Optional	The API name and ID of the modules such as Tasks, Meetings, or Calls. If the lead has one or all of these related records, the owner of these records will be changed to the user given in the “assign_to” key. Use the [Get Modules API](modules.yaml#$.paths./settings/modules.get) to get the ID of the module. Maximum items: 3
body.related_modules[]	object	Each item	Each object specifies the API name and ID of a related module to include in the conversion. Additional keys: not allowed
body.related_modules[].api_name	string	Required within parent	Specify the API name of the related module. Refer to the [Get Modules](modules.yaml#$.paths./settings/modules.get) resource for API name. Maximum length: 100
body.related_modules[].id	string	Required within parent	Specify the ID of the related module. Refer to the [Get Modules](modules.yaml#$.paths./settings/modules.get) resource for ID. Format: int64 Maximum length: 255

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 the mass convert job is successfully scheduled. Additional keys: not allowed
code	string	Required within parent	Represents the response code indicating the job has been scheduled. Possible values: SCHEDULED - The mass convert job has been accepted and scheduled for execution. Known values: SCHEDULED Maximum length: 50
details	object	Required within parent	Represents additional details about the scheduled mass convert job, including the job identifier. Additional keys: not allowed
details.job_id	string	Required within parent	Represents the unique identifier of the scheduled mass convert job, returned for use in subsequent job status requests. Maximum length: 255
message	string	Required within parent	Represents the message describing the outcome of the mass convert job scheduling. Maximum length: 512
status	string	Required within parent	Represents the status category of the response. Possible values: success* - The mass convert job was scheduled successfully. Known values: success Maximum length: 50

Policy, approvals and errors

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