Update a Rule in a Connected Workflow
Purpose
To update an existing rule in a connected workflow. You can modify trigger conditions, criteria, and actions of a rule using this API.
Endpoints
- PUT /settings/connected_workflows/{connected_workflow_ID}/rules/{rule_ID}
Request Details
Request URL
{api-domain}/crm/{version}/settings/connected_workflows/{connected_workflow_ID}/rules/{rule_ID}
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
ZohoCRM.settings.settings.connected_workflows.UPDATE
(or)
ZohoCRM.settings.settings.connected_workflows.ALL
(or)
ZohoCRM.settings.settings.ALL
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/settings/connected_workflows/4876876000020317001/rules/4876876000020520001"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"
-X PUTInput JSON
The request body must be a JSON object containing a rules array with exactly one object. The following keys are supported within that object:
- idstring, optional
Specify the unique ID of the rule to update. Use the Get Rule API to retrieve the rule ID.
- execute_whenJSON object, optional
Define when the rule triggers.
- typestring, mandatory
Specify the type of event that triggers the rule.
Possible values:
create - Trigger when a new record is created
edit - Trigger when an existing record is edited
create_or_edit - Trigger on both creation and edit
field_update - Trigger when a specific field value changes. - detailsJSON object, optional
Specify the details of the trigger.
- trigger_moduleJSON object, optional
Specify the module that triggers this rule. Provide the api_name or id of the module.
- criteriaJSON object, mandatory for field_update trigger
Specify the field conditions for field_update triggers. The criteria object must contain the field, the comparator, the type, and the value to compare against.
- repeatBoolean, optional
Define whether the rule should trigger repeatedly for subsequent updates. The default value is false.
- moduleJSON object, optional
Specify the module for the rule. Provide the api_name or id. Please note that the module of an existing rule cannot be changed.
- _nodeJSON object, mandatory for create_connected_record action
Specify the node where the rule is configured. Required for create_connected_record actions. The node ID must match the rule's module. Use the Get Workflow API to retrieve it.
- idstring, mandatory
Specify the unique ID of the node.
- conditionsJSON array, optional
An array containing one condition object that defines the actions to execute. Only one condition is supported per rule.
- idstring, optional
Specify the unique ID of the condition to update. Use the Get Rule API to retrieve the condition ID.
- instant_actionsJSON object, optional
Define instant actions to execute when the rule triggers.
- actionsJSON array, optional
Define action items. You can add up to 11 actions per condition.
- idstring, mandatory for associative actions
For associative actions (field_updates or email_notifications), specify the preconfigured action ID. Use the Get Field Update API or Get Email Notifications API to retrieve it.
- namestring, optional
Specify a name for the action.
- typestring, mandatory
Specify the type of action.
Possible values:create_connected_record, field_updates, email_notifications. - related_detailsJSON object, optional
Specify additional configuration details for associative actions (field_updates or email_notifications). This object defines which connected records the action should be applied to.
- record_selection_typestring, mandatory
Specify which records the action applies to.
Possible values:
all – Apply to all connected records.
current – Apply only to the triggering record.
selected – Apply to records matching the criteria object. - criteriaJSON object, mandatory if record_selection_type is selected
Define the filtering logic for selecting records to apply the action to. The criteria object must include the field details, the comparator, type, and value for comparison.
- detailsJSON object, mandatory for create_connected_record
Specify the action-specific configuration details for the create_connected_record action.
- moduleJSON object, mandatory
Specify the target module for the connected record. Provide the api_name and id.
- layoutJSON object, mandatory
Specify the layout for the new record. Provide the api_name and id.
- field_mappingsJSON array, mandatory
Define field mappings for the new record.
- fieldJSON object, mandatory
Specify the target field details. Provide both the api_name and the unique id of the field.
- typestring, mandatory
Specify the type of value.
Possible values:static, merge_field. - valuestring, mandatory
Specify the value. For static, provide a direct value. For merge_field, provide a merge field expression.
- apply_restrictionBoolean, optional
Specify if assignment rule restrictions apply when creating the record. Default: false.
- criteria_detailsJSON object, optional
Specify the filter conditions for the records. If specified, the actions will be performed only when the given criteria are satisfied. To clear existing criteria, set both relational_criteria and criteria to null.
- relational_criteriaJSON object, optional
Define trigger conditions based on related modules. These multi-module trigger criteria execute actions when related module records meet the conditions.
- criteria_groupingsJSON array, mandatory
Specify a list of independent criteria groups, each checking a condition in a specific related module. Up to 3 criteria groupings are supported. The logical combination of these groups is defined by the pattern key.
- sequence_numberinteger, mandatory
Specify the order number of this criteria group. This value is referenced in the logical pattern expression.
- criteriaJSON object, mandatory
Specify the condition details. The criteria object must contain the field, the comparator, the type, and the value to compare the field against.
- moduleJSON object, mandatory
Specify the related module to evaluate. Provide either the api_name or the unique id of the module.
- match_typestring, mandatory
Define whether any or all connected records in the specified module must meet the condition for this grouping to evaluate as true.
- patternstring, mandatory
Specify the logical expression used to combine multiple criteria groupings using operators such as and and or, based on their sequence_number. If there is only one criteria grouping, the pattern value must match its sequence number (for example, "(1)"). Maximum allowed length is 15 characters.
- criteriaJSON object, optional
Specify trigger criteria for the primary module. Actions execute only when these conditions are met. Include field, comparator, type, and value.
- fieldJSON object, mandatory
Specify the field to evaluate. Provide the api_name and id.
- comparatorstring, mandatory
Specify the comparison operator used in the condition.
- typestring, mandatory
Specify the type of value used for comparison.
- valuestring, mandatory
Specify the value against which the field is evaluated.
Note
- You can only update one rule per API request. Multiple rules require multiple API calls.
- The module field is read-only and cannot be changed during update. The system will throw an error if you try to update the module.
- Maximum 11 actions can be configured per condition.
- The _node.id must be included and must match the node where the rule was originally created.
- Sequence numbers in criteria groupings must be sequential (1, 2, 3) and match the pattern.
- To remove an action from a rule, include the _delete key with the value set to null in the action object, along with the corresponding action ID. This will delete the specified action from the rule.
- This API supports partial updates, allowing you to modify only specific fields in a rule.
However, the criteria_details.relational_criteria and criteria_details.criteria sections must be provided in full when included in the request. These sections do not support partial updates and will be completely replaced.
Sample Input
Copied{
"rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"repeat": true
},
"type": "create_or_edit"
},
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"_node": {
"id": "4876876000020520028"
},
"conditions": [
{
"instant_actions": {
"actions": [
{
"name": "Create Onboarding Record",
"details": {
"layout": {
"name": "Standard",
"id": "4876876000019056016"
},
"field_mappings": [
{
"display_value": "${CURRENTUSER}",
"field": {
"api_name": "Owner",
"id": "4876876000019056061"
},
"type": "static",
"value": {
"name": "${CURRENTUSER}"
}
},
{
"display_value": "${CURRENTRECORD}",
"field": {
"api_name": "Customer_name",
"id": "4876876000019057269"
},
"type": "merge_field",
"value": "${!CURRENTRECORD}"
}
],
"module": {
"api_name": "Customer_Onboarding",
"id": "4876876000019056017"
},
"apply_restriction": false
},
"id": "4876876000020520023",
"type": "create_connected_record"
},
{
"name": "Send Welcome Email",
"id": "4876876000021399001",
"type": "email_notifications"
}
]
},
"criteria_details": {
"relational_criteria": {
"criteria_groupings": [
{
"sequence_number": 1,
"criteria": {
"group_operator": "OR",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Mailing_Country",
"id": "4876876000000002549"
},
"type": "value",
"value": "United States"
},
{
"comparator": "equal",
"field": {
"api_name": "Mailing_Country",
"id": "4876876000000002549"
},
"type": "value",
"value": "Canada"
}
]
},
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"match_type": "all"
},
{
"sequence_number": 2,
"criteria": {
"comparator": "not_equal",
"field": {
"api_name": "Email",
"id": "4876876000000002599"
},
"type": "value",
"value": "${EMPTY}"
},
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"match_type": "all"
}
],
"pattern": "(1and2)"
},
"criteria": {
"group_operator": "AND",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Data_Source",
"id": "4876876000000338211"
},
"type": "value",
"value": "Manual (Mobile)"
},
{
"comparator": "not_equal",
"field": {
"api_name": "Phone",
"id": "4876876000000002601"
},
"type": "value",
"value": "${EMPTY}"
}
]
}
},
"id": "4876876000020520002"
}
]
}
]
}Possible Errors
- FEATURE_NOT_SUPPORTEDHTTP 400
Your edition doesn't support this feature
Resolution: Upgrade the account to Standard, Professional, Enterprise, or Ultimate edition and then retry the request. - INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: This API supports only the GET method. Retry the request using the GET method. - MANDATORY_NOT_FOUNDHTTP 400
Required field not found
Resolution: One or more mandatory fields are missing in the input JSON. The name of the missing field and its location can be found in the message and json_path keys of the error response. - INVALID_DATAHTTP 400
- Invalid data
Resolution: You have provided an invalid data for one or more fields. additional information can be found in the details key in the error response. - Invalid connected workflow ID
Resolution: The workflow ID in the URL path is invalid or does not exist. Verify the workflow ID using the GET connected workflows API. - The given module doesn't exist
Resolution: The module specified in the request does not exist. Verify the module name and try again. - Action is already configured in some other rules
Resolution: The action is already associated with another rule. Create another action and associate it with the rule. - The given node ID is invalid.
Resolution: Provide a valid _node.id obtained from the connected workflow's nodes array. - Other feature_type action cannot be associated to Connected workflow Rules
Resolution: Ensure that the action is created with feature_type = connected_workflows before associating it with the rule. - Encrypted Field is not supported for given operator
Resolution: Use a supported comparator for encrypted fields in the criteria. - The given tag is not available
Resolution: Provide a valid tag that exists in the module. - Invalid pattern
Resolution: The criteria pattern syntax is incorrect or doesn't match the number of criteria groupings. Ensure the pattern uses valid syntax (e.g., "(1and2)", "(1or2)") and matches the number of groupings. - Sequence Number is more than the available number of records
Resolution: Sequence numbers are not sequential or exceed the number of groupings. Use sequential numbers starting from 1 (e.g., 1, 2, 3) that match your criteria groupings count. - This given actionid seems to be invalid
Resolution: The action ID provided is invalid or does not exist. Verify the action ID and try again.
- Invalid data
- AMBIGUITY_DURING_PROCESSINGHTTP 400
Ambiguity while processing the request
Resolution: Both module id and api_name are provided but they reference different modules. Provide either id OR api_name, or ensure they reference the same module. - EXPECTED_FIELD_MISSINGHTTP 400
Required field not found
Resolution: One or more mandatory fields are missing in the input JSON. The name of the missing field and its location can be found in the message and json_path keys of the error response. - DUPLICATE_DATAHTTP 400
Duplicate action found
Resolution: One or more actions in the input JSON are duplicates. Ensure each action is unique and try again. - NOT_ALLOWEDHTTP 400
- Module cannot be updated
Resolution: The module field is read-only during updates. You cannot change the module for an existing rule. If you need to change the module, delete the rule and create a new one. - An unsupported action is given
Resolution: Invalid action type provided or action type not supported for connected workflows. Use only supported action types: create_connected_record, field_updates, email_notifications
- Module cannot be updated
- CRITERIA_LIMIT_EXCEEDEDHTTP 400
Number of fields in execute_when has exceeded the limit
Resolution: Ensure that only one criteria field is provided. - LOOKUP_LIMIT_EXCEEDEDHTTP 400
Lookups count exceeded the limit
Resolution: Ensure that lookup fields used in criteria do not exceed five. - LIMIT_EXCEEDEDHTTP 400
- Actions limit exceeded
Resolution: More than the allowed number of actions are included. Reduce the number of actions to the allowed limit. Check the limit value in error details for your edition's limit. - Conditions Limit Exceeds
Resolution: More than one condition block is included in the request. Include only one condition block per rule. - criteria_groupings in criteria has exceeded the limit
Resolution: More than three relational criteria groupings are included. Reduce criteria groupings to a maximum of three. - More modules cannot be used in the connected workflow.
Resolution: Ensure that the number of modules configured does not exceed the maximum permitted value. For more details on the limits for your CRM edition, please refer to our Features List page.
- Actions limit exceeded
- DEPENDENT_MISMATCHHTTP 400
- When repeat is disabled current record criteria should be given
Resolution: Provide criteria_details.criteria when repeat is false. - Repeat not supported for this trigger
Resolution: Remove repeat or use a supported trigger type. - For current record field_update module and trigger module should be same
Resolution: Ensure both modules match.
- When repeat is disabled current record criteria should be given
- DEPENDENT_FIELD_MISSINGHTTP 400
Dependent Field missing
Resolution:- When updating field_updates or email_notifications actions, the action id field is required. Include the existing action ID in your request.
- For create_connected_record actions, the details object is mandatory. Include the complete details configuration with module, layout, and field mappings.
- OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: Client does not have the required OAUTH SCOPE. Create a new token with valid scope. Refer to the Scope section for more details. - NO_PERMISSIONHTTP 403
Permission denied
Resolution: Ensure that the user making the API call has the Manage Autiomations or Connected Workflows permission enabled in their CRM profile, and then retry the request. - INVALID_URL_PATTERNHTTP 404
Please check if the URL trying to access is a correct one
Resolution: The request URL specified is incorrect. Specify a valid request URL. Refer to request URL section for more details. - INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team.
Sample Response
Copied{
"rules": [
{
"code": "SUCCESS",
"details": {
"id": "4876876000020520001"
},
"message": "connected workflow rule updated successfully",
"status": "success"
}
]
}