Zoho: Create an Automation Task

← Workflow tasks operations · Get started

Operation zoho.createworkflowtasks

Provider route: POST /crm/v8/settings/automation/tasks. 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["workflowTasks"]["createWorkflowTasks"]>[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.workflowTasks.createWorkflowTasks(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.workflow_tasks.create_workflow_tasks(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
body	Model	Optional	Expand Create an Automation Task — request body — body

Referenced models: Create an Automation Task — request body — body

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
$	Model	Root	Expand Create an Automation Task — response body

Referenced models: Create an Automation Task — response body

Schemas

7 more schemas are linked from the tables above, on the schema pages.

Create an Automation Task — response body

Field	Type	Presence	Description and constraints
$	object	Root	Successful response after creating an automation task definition. Additional keys: not allowed
tasks	array	Required within parent	Array containing the created task result. Maximum items: 1
tasks[]	Model	Each item	Expand Create an Automation Task — response body — tasks item

Referenced models: Create an Automation Task — response body — tasks item

Create an Automation Task — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	PURPOSE: Request body wrapper for creating or updating an automation task definition. MUST contain a tasks array with exactly 1 task object. Additional keys: not allowed
tasks	array	Required within parent	REQUIRED. Array containing exactly 1 automation task object. Multiple tasks per request are not supported. Maximum items: 1 Minimum items: 1
tasks[]	Model	Each item	Expand Create an Automation Task — request body — body tasks item

Referenced models: Create an Automation Task — request body — body tasks item

Create an Automation Task — response body — tasks item

Field	Type	Presence	Description and constraints
$	object	Root	Result of a task create, update, or delete operation. Additional keys: not allowed
code	string	Required within parent	Operation result code (e.g., SUCCESS). Maximum length: 255
details	Model	Required within parent	Expand Create an Automation Task — response body — tasks item details
message	string	Required within parent	Result message describing the outcome of the task action. Maximum length: 255
status	string	Required within parent	Operation result status (e.g., success). Maximum length: 255

Referenced models: Create an Automation Task — response body — tasks item details

Create an Automation Task — request body — body tasks item

Field	Type	Presence	Description and constraints
$	object	Root	PURPOSE: Writable task fields for create or update. PREREQUISITES: (1) Call GET /settings/layouts?module=Tasks - fields with required: true in the field info are mandatory in field_mappings. (2) Call GET /settings/modules to discover valid module api_names. Read-only fields (id, created_time, modified_time, created_by, modified_by, lock_status, associated, deletable) are excluded. Additional keys: not allowed
feature_type	string	Optional	The automation feature this task definition belongs to. Defaults to "workflow" if omitted. A task can only be associated with the feature it was created for - a task with feature_type="workflow" can only be attached to workflow rules, not to blueprints or kiosks. Supported values are defined in the enum. Default: workflow One of: workflow, approval_process, blueprint, blueprint_transition, blueprint_state, review_process, orchestration, assignment_rules, kiosks, pathfinder, connected_workflows, commandcenter_service, cadences, scoring_rule, case_escalation_rule Maximum length: 255
field_mappings	array	Required within parent	REQUIRED. Field mappings for task fields. Mandatory mappings: Subject (static or merge_field), Due_Date (execution_time), Status (static: Not Started, Deferred, In Progress, Completed, Waiting on someone else), Priority (static: Highest, High, Normal, Low, Lowest). Optional: Description, Owner, Remind_At (execution_time). Each entry requires field ({api_name, id}), type, and value. Types: static (literal values), merge_field (${!Module.Field} tokens), execution_time (for Date/DateTime/ALARM - requires period, unit, trigger_field, sign). Workflow tasks support period: days, business_days only. Max 20 entries. Maximum items: 20 Minimum items: 1
field_mappings[]	Model	Each item	Expand Create an Automation Task — request body — body tasks item field mappings item
module	Model	Required within parent	Expand Create an Automation Task — request body — body tasks item module
name	string	Required within parent	Display name for this task definition. Must be identical to the value provided in the Subject field_mapping entry. If they do not match, the API returns INVALID_DATA. For merge_field type Subject mappings, set name to the same token string (e.g., "${!Leads.Last_Name}"). Maximum length: 255
notify	boolean	Optional	Whether notification should be sent to the task owner when this automation task executes. Default: false

Referenced models: Create an Automation Task — request body — body tasks item field mappings item, Create an Automation Task — request body — body tasks item module

Create an Automation Task — response body — tasks item details

Field	Type	Presence	Description and constraints
$	object	Root	Details returned with a task action result, including the created or affected resource ID. Additional keys: not allowed
id	string	Required within parent	Unique ID of the created or affected automation task. Maximum length: 20
resource_path_index	string	Optional	Index of the resource in the request payload array. Maximum length: 255

Create an Automation Task — request body — body tasks item field mappings item

Field	Type	Presence	Description and constraints
$	JSON	Root	Represents a single field-to-value mapping used within automation actions such as workflow tasks, create_record, add_meeting, and schedule_call. Each mapping identifies a target field via api_name or ID, declares a type discriminator that determines value interpretation, and supplies a value whose shape varies by type: static supplies a literal value, merge_field supplies a runtime-resolved token string, execution_time supplies a date or datetime offset object, and composite supplies structured participant data for the Events Participants field. The field_mappings array must include all fields the target module requires; omitting any produces a REQUIRED_DATA_NOT_FOUND error. discriminator: {"mapping": {"composite": "#/components/schemas/CompositeFieldMapping", "execution_time": "#/components/schemas/ExecutionTimeFieldMapping", "merge_field": "#/components/schemas/MergeFieldMapping", "static": "#/components/schemas/StaticFieldMapping"}, "propertyName": "type"}
$ (anyOf 1)	Model	Alternative	Expand Create an Automation Task — request body — body tasks item field mappings item type static
$ (anyOf 2)	Model	Alternative	Expand Create an Automation Task — request body — body tasks item field mappings item type merge field
$ (anyOf 3)	Model	Alternative	Expand Create an Automation Task — request body — body tasks item field mappings item type execution time
$ (anyOf 4)	Model	Alternative	Expand Create an Automation Task — request body — body tasks item field mappings item type composite

Referenced models: Create an Automation Task — request body — body tasks item field mappings item type composite, Create an Automation Task — request body — body tasks item field mappings item type execution time, Create an Automation Task — request body — body tasks item field mappings item type merge field, Create an Automation Task — request body — body tasks item field mappings item type static

Create an Automation Task — request body — body tasks item module

Field	Type	Presence	Description and constraints
$	object	Root	PURPOSE: The CRM module this task definition belongs to. Specifies which module's records will trigger task creation - not the Tasks module itself. PREREQUISITES: Call GET /settings/modules to discover available module api_names and IDs. api_name is required, id is optional. Additional keys: not allowed
api_name	string	Required within parent	REQUIRED. API name of the CRM module whose records trigger this task creation (e.g., Leads, Contacts, Deals). Use GET /settings/modules to discover available modules. Maximum length: 255
id	string	Optional	Optional module ID. If provided alongside api_name, both must refer to the same module. Maximum length: 255

Create an Automation Task — request body — body tasks item field mappings item type composite

Field	Type	Presence	Description and constraints
$	object	Root	Represents a composite-type field mapping used exclusively for the Participants field in the Events module via the add_meeting action. The value carries a structured object that encodes participant data and is not applicable to any other field or automation action type. Additional keys: not allowed
display_value	string	Optional	The server-computed representation of the mapped value, included in GET responses. Omitted from create and update requests. Maximum length: 500
field	Model	Required within parent	Expand Create an Automation Task — request body — body tasks item field mappings item type static field Target field to populate when the automation executes. api_name is required. If id is also provided, both must refer to the same field; otherwise the API returns AMBIGUITY_DURING_PROCESSING.
type	string	Required within parent	Serves as the polymorphic discriminator that identifies this field mapping as a composite mapping; the value must be set to "composite" to select this schema variant. Must equal: composite
value	object	Required within parent	Holds the structured composite object that encodes participant data for the Events module Participants field; the shape of this object varies according to the participant type configuration defined for the automation rule. Additional keys: allowed

Referenced models: Create an Automation Task — request body — body tasks item field mappings item type static field

Policy, approvals and errors

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