Zoho: Create a workflow rule for a module

← Workflow rules operations · Get started

Operation zoho.postworkflowrule

Provider route: POST /crm/v8/settings/automation/workflow_rules. 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["workflowRules"]["postWorkflowRule"]>[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.workflowRules.postWorkflowRule(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_rules.post_workflow_rule(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 a workflow rule for a module — request body — body

Referenced models: Create a workflow rule for a module — 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 Update Workflow Rule by ID — response body

Referenced models: Update Workflow Rule by ID — response body

Schemas

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

Update Workflow Rule by ID — response body

Field	Type	Presence	Description and constraints
$	object	Root	Represents the success response returned after creating a workflow rule, containing the result details of the created rule. Additional keys: not allowed
workflow_rules	array	Optional	Represents the array of workflow rule objects returned in the success response. Maximum items: 200
workflow_rules[]	Model	Each item	Expand Update Workflow Rule Execution Order for Module — response body — reorder item

Referenced models: Update Workflow Rule Execution Order for Module — response body — reorder item

Create a workflow rule for a module — request body — body

Field	Type	Presence	Description and constraints
$	object	Root	Represents the request body wrapper for creating a new workflow rule. Contains a single-element array with the workflow rule configuration. Additional keys: not allowed
workflow_rules	array	Required within parent	Represents the array containing the workflow rule object to create. The array must contain exactly one object per request. Maximum items: 1
workflow_rules[]	Model	Each item	Expand Create a workflow rule for a module — request body — body workflow rules item

Referenced models: Create a workflow rule for a module — request body — body workflow rules item

Update Workflow Rule Execution Order for Module — response body — reorder item

Field	Type	Presence	Description and constraints
$	object	Root	Represents a single item in a multi-status response array, including a response code, status indicator, message, and optionally the resource details. Additional keys: not allowed
code	string	Optional	Represents the API response code indicating the operation result, such as **SUCCESS** or **INVALID_DATA**. Maximum length: 255
details	Model	Optional	Expand Update Workflow Rule Execution Order for Module — response body — reorder item details
message	string	Optional	Represents the message describing the operation result or error. Known values: workflow created, workflow updated, workflow deleted, WorkFlow Rule deleted successfully, rules reordered successfully, Workflow cloned successfully
status	string	Optional	Represents the response status indicator, such as **success** or **error**. Maximum length: 7

Referenced models: Update Workflow Rule Execution Order for Module — response body — reorder item details

Create a workflow rule for a module — request body — body workflow rules item

Field	Type	Presence	Description and constraints
$	object	Root	Represents the configuration object for a new workflow rule, including required fields such as name, target module, and trigger configuration. Additional keys: not allowed
conditions	array	Required within parent	Specify the conditions that define the branching logic of the workflow rule. Each condition evaluates records against criteria and executes its own set of actions. At least one condition is required. Maximum items: 10
conditions[]	Model	Each item	Expand Update Workflow Rule by ID — request body — body workflow rules item conditions item
description	string or null	Optional	Specify an optional description for the workflow rule. Set to null to clear an existing description. Maximum length: 1000
execute_when	Model	Required within parent	Expand Update Workflow Rule by ID — request body — body workflow rules item execute when Specifies when the workflow rule is triggered. This is a required JSON object with "type" and "details" properties. For example: {"type": "create_or_edit", "details": {"trigger_module": {"api_name": "Leads", "id": "..."}, "repeat": false}}. Passing a string instead of a JSON object, such as "create_or_edit", returns an "INVALID_DATA" error. The "details.trigger_module" must match the module associated with the workflow rule. Use "getWorkflowConfigurations" to retrieve the available triggers and their supported actions.
lock	object	Optional	Specify the lock configuration to prevent other users from editing the rule. Only administrators can lock or unlock rules. Additional keys: not allowed
lock.message	string	Optional	Specify the reason or context for locking the rule. Valid only when **lock.status** is set to true. Format: string
lock.status	boolean	Optional	Specify whether to lock the rule. Possible values: true - Locks the rule to prevent editing. false - Unlocks the rule.
module	Model	Required within parent	Expand List Workflow Rules in your Zoho CRM Organization — response body — workflow rules item module The module to which the workflow rule applies. Use the [Get Modules API](modules.yaml#$.paths./settings/modules.get) to retrieve module IDs. Required. Must be a workflow-supported module. If both id and api_name are provided, they must match. Use `getWorkflowConfigurations` to discover supported modules. Cannot be changed after creation.
name	string	Required within parent	Specify the workflow rule name. Required. Cannot exceed 100 characters. Special characters are not allowed. Maximum length: 100

Referenced models: Update Workflow Rule by ID — request body — body workflow rules item conditions item, Update Workflow Rule by ID — request body — body workflow rules item execute when, List Workflow Rules in your Zoho CRM Organization — response body — workflow rules item module

Update Workflow Rule Execution Order for Module — response body — reorder item details

Field	Type	Presence	Description and constraints
$	object	Root	Represents the details object within a success response, containing the unique ID of the created or updated resource. Additional keys: not allowed
id	string	Optional	Represents the unique ID of the SuccessResponseDetails within the workflow rule. Maximum length: 255

Update Workflow Rule by ID — request body — body workflow rules item conditions item

Field	Type	Presence	Description and constraints
$	object	Root	Represents a single condition within a workflow rule that defines which records are evaluated and what actions are executed when the criteria are met. Additional keys: not allowed
_delete	null	Optional	Indicates that this condition should be removed from the workflow rule when set in a PUT request. Provide a null value to signal deletion.
criteria_details	Model	Optional	Expand Update Workflow Rule by ID — request body — body workflow rules item conditions item criteria details Record matching criteria for this condition. When provided, criteria_details must be a JSON object and cannot be null. To match all records, pass an object with criteria set to null, but do not set criteria_details itself to null. This field is required for certain trigger types, such as related module triggers like Notes on Leads. The convert action type requires criteria_details.criteria to be a non-null filter object. Omit criteria_details entirely or pass criteria as null to match all records when the trigger does not require specific criteria and no convert action is present.
id	string	Optional	Represents the unique ID of the condition. Auto-generated on creation. Required on PUT to identify which condition to update. Format: int64
instant_actions	Model	Optional	Expand Update Workflow Rule by ID — request body — body workflow rules item conditions item instant actions Actions to execute immediately when the condition is met. At least one of instant_actions or scheduled_actions must be present - returns MANDATORY_NOT_FOUND if both are absent.
scheduled_actions	Model	Optional	Expand Update Workflow Rule by ID — request body — body workflow rules item conditions item scheduled actions Actions to execute after a configured delay. Scheduled actions require both the trigger and the action type to support scheduling.
sequence_number	integer	Required within parent	Represents the execution order of this condition within the workflow rule, starting from one. Must be unique across all conditions in the rule. Format: int32

Referenced models: Update Workflow Rule by ID — request body — body workflow rules item conditions item criteria details, Update Workflow Rule by ID — request body — body workflow rules item conditions item instant actions, Update Workflow Rule by ID — request body — body workflow rules item conditions item scheduled actions

List Workflow Rules in your Zoho CRM Organization — response body — workflow rules item module

Field	Type	Presence	Description and constraints
$	object	Root	Represents a CRM module or field reference using its API name and unique numeric ID. Minimum fields: 1 Additional keys: not allowed
api_name	string	Required within parent	Represents the API name of the module or field, such as **Leads**, **Contacts**, or a custom field API name. Maximum length: 100
id	string	Required within parent	Represents the unique numeric ID of the module or field. Maximum length: 20

Update Workflow Rule by ID — request body — body workflow rules item execute when details, type — Execute When T3 Section Update

Field	Type	Presence	Description and constraints
$	object	Root	Represents the trigger type for section update rules. Availability varies by the target module Additional keys: not allowed
details	Model	Required within parent	Expand List Workflow Rules in your Zoho CRM Organization — response body — workflow rules item execute when details, type details — shared_details_be3cf6ec2c47
type	string	Required within parent	Represents the trigger type for section update rules. Use getWorkflowConfigurations to verify the trigger is available for the target module. One of: section_update, incoming_call_section_update, outgoing_call_section_update, scheduled_call_section_update

Referenced models: List Workflow Rules in your Zoho CRM Organization — response body — workflow rules item execute when details, type details — shared_details_be3cf6ec2c47

Policy, approvals and errors

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