Update Workflow Rule

Purpose

To update a Workflow rule in Zoho CRM. You can modify the rule’s name, description, triggers (with restrictions), criteria, conditions, and actions. You can also activate or deactivate the workflow rule.

Endpoints

PUT /settings/automation/workflow_rules
PUT /settings/automation/workflow_rules/{rule_id}

Request Details

Request URL

{api-domain}/crm/{version}/settings/automation/workflow_rules
{api-domain}/crm/{version}/settings/automation/workflow_rules/{rule_ID}

Note:

If the ID is included in the URL, only this ID will be considered. Any ID passed in the request body will be ignored.
If the ID is not included in the URL, then it is mandatory to specify the ID in the request body.

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.workflow_rules.ALL
(or)
ZohoCRM.settings.workflow_rules.UPDATE

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/workflow_rules"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @updateworkflow.json
-X PUT

Input JSON

The request body follows the same structure as the Create Workflow Rule API. It must include a workflow_rules array, where each element represents a workflow rule. For the Update Workflow Rule API, this array can contain only one object per request.

Possible Updates

You can update the following properties of a workflow rule:

Trigger : A trigger can be updated, but only within the same trigger type. You cannot update a trigger to a different type. For instance, changing from a Record Action trigger to a Score-based trigger is not allowed.
Name and description of the workflow rule.
Actions: Add or remove actions.
Conditions: Add or remove conditions.
Criteria: Modify or replace criteria logic.
Status: Activate or deactivate the workflow rule.

Note:

You cannot update the module or the trigger module of a Workflow Rule.
Trigger type cannot be changed across categories.
When you update a trigger to another trigger within the same type, and existing actions are not supported for the new trigger, the API will return an error. For example, changing trigger from edit to delete while retaining an Assign Owner action will result in an error, since Assign Owner is not supported for delete triggers.
To delete an existing condition or action, set the _delete key to null.

The table below lists the supported trigger types and their possible values. Use this as a reference when updating triggers to ensure that the new value belongs to the same type as the existing one.

Trigger Type	Possible Values
Record action	create, edit, create_or_edit, delete, field_update, section_update
Roll-up summary	rollup_summary_update
Zia recommendation	recommendation
Date and Datetime triggers	date_or_datetime
Scoring Rule	score_increase, score_decrease, score_update
Calls module	scheduled_call_field_update, scheduled_call_section_update, scheduled_call_edit, scheduled_call_createedit, outgoing_call_ring, outgoing_call_start, outgoing_call_section_update, outgoing_call_createedit, outgoing_call_field_update, outgoing_call_edit, incoming_call_ring, incoming_call_start, incoming_call_edit, incoming_call_field_update, incoming_call_createedit, incoming_call_section_update, anyaction, delete, missed_call
Appointments module	create, reschedule, cancel, reassign, delete, overdue, marked_as_complete, anyaction
Emails module	email_received, mail_sent, mail_sent_clicked, mail_sent_replied, mail_sent_opened, mail_sent_bounced, email_received_notreplied, email_received_opened_notreplied, mail_sent_replied_within, mail_sent_opened_notreplied, mail_sent_notreplied, mail_sent_notopened
Facebook Trigger	fb_post_on_page, fb_comment_on_page, fb_like_on_post, fb_send_message
Twitter Trigger	tw_mention_on, tw_retweet_on_tweet, tw_comment_on_tweet, tw_send_message

idstring, mandatory if not specified in the URL
Specify the ID of the workflow rule to be updated.
execute_whenJSON object, optional
Specify this object if you want to update the trigger. This object must contain the details of the trigger.
- detailsJSON object, optional
  Specify details about the trigger, if any.
- typestring, optional
  Specify the trigger. Possible values are listed in the table.
namestring, optional
Specify the Workflow name.
descriptionstring, optional
Specify the Workflow description.
lockJSON object, optional
Specify whether the workflow rule should be locked for editing by other users.
- messagestring, mandatory only when lock.status is true
  A note or label to indicate the reason or context for locking the rule.
- statusBoolean, mandatory
  Specify whether the workflow rule should be locked or not.
  Possible values:
  true - The workflow will be locked.
  false - The workflow will not be locked. This is the default value.
conditionsJSON array, optional
An array of condition objects that define the criteria for executing the actions.
- idstring, optional
  If you want to update or delete an exisitng condition, specify the condition ID.
- sequence_numberinteger, mandatory
  Represents the execution order for the criteria. The index starts from 1.
- criteria_detailsJSON object, optinal
  Specifies the conditions a record must meet for the workflow rule to apply. Set this to nullto apply the rule to all records in the module.
  - criteriaJSON object, optional
    The main condition applied on the triggering module’s fields. Set this to null to apply the rule to all records.
  - relational_criteriaJSON object, optional
    Specify conditions based on a related module’s records. The relational_criteria key is supported only in triggers where the workflow can be evaluated against records in a related module. Examples include Email triggers, Call triggers, social media triggers, Notes triggers, and Appointment module triggers. It is not applicable for purely time-based triggers or triggers restricted to the same module without related-record checks.
    - module_selectionJSON object, optional
      Specify the details of the related record to be evaluated.
      Possible values:
      all – Evaluate criteria against all related records.
      specific – Evaluate criteria against a specific related module provided in the module key.
      unknown – Used when the related entity is not a record in any CRM module. For example, in an email_received trigger, when the sender is not a Lead or Contact, use this value.
    - criteriaJSON object, optional
      Specify the condition to apply on the related module’s fields. Follows the same structure as the main criteria object. Set to null when no related record condition is needed.
    - moduleJSON object, optional
      The related module details. This key is mandatory if module_selection is specific.
- instant_actionsJSON object, optional
  The list of Instant Actions to execute immediately when condition is met.
  - actionsJSON array, optional
    An array of action objects, each containing the following:
    - idstring, optional
      If you want to update or delete an exisitng action, specify the action ID.
    - typestring, mandatory
      Specify the type of action (e.g., field_updates, email_notifications, tasks, add_tags, create_record, etc.).
    - idstring, mandatory for associative actions
      Specify the unique ID of the action.
      Depending on the action type, you must use the corresponding Get API to fetch the valid action IDs.
    - related_detailsJSON object, mandatory
      Additional information depending on action type (e.g., follow-ups for tasks, tags for add_tags, etc.).
- scheduled_actionsJSON array, optional
  Specify the list of scheduled actions that are to be executed after a delay, once conditions are met.
  - execute_afterJSON object, mandatory
    Specify the delay before the action executes.
    - periodstring, mandatory
      The time unit.
      Possible values : b_days, b_hours, hrs
    - unitinteger, mandatory
      The number of time units to wait before executing the scheduled action.
  - actionsJSON array, mandatory
    The list of scheduled actions.
    - idstring, optional
      If you want to update or delete an exisitng action, specify the action ID.
    - typestring, mandatory
      Specify the type of action.
    - idstring, mandatory for associative actions
      Specify the unique ID of the action.
      Depending on the action type, you must use the corresponding Get API to fetch the valid action IDs.
    - related_detailsJSON object, mandatory
      Additional information depending on action type (e.g., follow-ups for tasks, tags for add_tags, etc.).

Note:

Ensure that sequence_number values are sequential integers starting from 1. Broken sequence (e.g., 1, 4) or repeated numbers will result in an error.
Rule names must not contain special characters such as # % ^ & * ( ). The maximum limit for rule is 100 characters.
Triggers have specific constraints on what actions are supported. Use the Get Workflow Configurations API to check which triggers support which actions.
When repeat is set to true, scheduled actions are not supported.

Sample Input to update name and trigger

Copied{
  "workflow_rules": [
    {
      "execute_when": {
        "details": {
          "repeat": true
        },
        "type": "edit"
      },
      "name": "Updated Rule Name"
    }
  ]
}

Sample input to add and remove actions

Copied{
  "workflow_rules": [
    {
      "conditions": [
        {
          "id": "4876876000015005002",
          "instant_actions": {
            "actions": [
              {
                "details": {
                  "tags": [
                    {
                      "name": "TagB",
                      "id": "4876876000002526117",
                      "color_code": ""
                    },
                    {
                      "name": "Active",
                      "id": "4876876000001143001",
                      "color_code": "#F17574"
                    }
                  ]
                },
                "id": "4876876000015005009",
                "type": "add_tags",
                "_delete": null
              },
              {
                "id": "4876876000000329765",
                "type": "tasks"
              }
            ]
          }
        }
      ]
    }
  ]
}

Sample input to add and remove conditions

Copied{
  "workflow_rules": [
    {
      "id": "4876876000015014033",
      "conditions": [
        {
          "id": "4876876000015014036",
          "_delete": null
        },
        {
          "sequence_number": 1,
          "instant_actions": {
            "actions": [
              {
                "related_details": null,
                "details": {
                  "apply_assignment_threshold": true,
                  "assign_to": [
                    {
                      "resource": {
                        "name": "Patricia Boyle",
                        "id": "4876876000000327001",
                        "type": "user"
                      },
                      "details": null,
                      "type": "user"
                    }
                  ],
                  "module": {
                    "api_name": "Leads",
                    "id": "4876876000000002175"
                  },
                  "related_records": null,
                  "user_availability_based_on": null,
                  "notify": false
                },
                "type": "assign_owner"
              },
              {
                "details": {
                  "module": {
                    "api_name": "Leads",
                    "id": "4876876000000002175"
                  },
                  "over_write": false,
                  "tags": [
                    {
                      "name": "P1",
                      "id": "4876876000011037076",
                      "color_code": "#F17574"
                    },
                    {
                      "name": "Active",
                      "id": "4876876000001143001",
                      "color_code": "#F17574"
                    }
                  ]
                },
                "type": "add_tags"
              }
            ]
          },
          "scheduled_actions": null,
          "criteria_details": {
            "relational_criteria": {
              "module_selection": null,
              "criteria": null,
              "module": null
            },
            "criteria": {
              "comparator": "greater_than",
              "field": {
                "api_name": "Annual_Revenue",
                "id": "4876876000000002617"
              },
              "type": "value",
              "value": "999999999999999"
            }
          }
        }
      ]
    }
  ]
}

Sample input to update criteria

Copied{
    "workflow_rules": [
        {
            "id": "4876876000015014033",
            "conditions": [
                {
                    "id": "4876876000015013021",
                    "criteria": {
                        "group_operator": "AND",
                        "group": [
                            {
                                "comparator": "greater_than",
                                "field": {
                                    "api_name": "Annual_Revenue",
                                    "id": "4876876000000002617"
                                },
                                "type": "value",
                                "value": "999999999999999"
                            },
                            {
                                "comparator": "contains",
                                "field": {
                                    "api_name": "Company",
                                    "id": "4876876000000002591"
                                },
                                "type": "value",
                                "value": "Zylker"
                            }
                        ]
                    }
                }
            ]
        }
    ]
}

Update the status of a Workflow rule

You can update the status of a workflow rule to either activate or deactivate it. To do this, you must include the status object in the request body, inside the workflow rule definition.

idstring, mandatory
The unique identifier of the workflow rule to be updated.
statusJSON object, mandatory for status updates
Defines the status of the workflow rule.
- activeBoolean, mandatory
  Specify whether to activate or deactivate the Workflow rule.
  Possible values:
  true - Activate the workflow rule
  false - deactivate the workflow rule
- delete_schedule_actionBoolean, mandatory only when deactivating a rule
  Specify whether to retain or delete the scheduled actions when the Workflow rule is deactivated.
  Possible values:
  true - Delete all scheduled actions associated records, related to the workflow rule.
  false (default) - Retain all scheduled actions associated records, related to the workflow rule.

Sample Input to activate a workflow rule

Copied{
    "workflow_rules": [
        {
            "id": "4876876000011150005",
            "status": {
                "active": true
            }
        }
    ]
}

Sample Input to deactivate a workflow rule

Copied{
    "workflow_rules": [
        {
            "id": "4876876000011150005",
            "status": {
                "active": true
            }
        }
    ]
}

Possible Errors

INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to the endpoints section for more details.
DEPENDENT_MISMATCHHTTP 400
- Repeat not supported for this trigger
  Resolution: The repeat key is only supported for specific trigger types such as edit and create_or_edit. Remove the repeat key from the input or use a valid trigger type that supports it.
- The dependent value should be null for the selected trigger
  Resolution: A field value has been provided that is not applicable for the selected trigger. Remove or set the dependent field to null as required for this trigger type.
- Given Unit is not supported for the period.
  Resolution: The value provided for the unit key is not valid for the specified period. Use a unit that is supported for the specified period.
MANDATORY_NOT_FOUNDHTTP 400
A required field is missing
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.
DEPENDENT_FIELD_MISSINGHTTP 400
- A dependent field is missing
  Resolution: One or more required dependent fields are missing in the input JSON. Check the details object in the response to identify the missing dependent field. Based on the value of the field it depends on, include the required field in your input.
INVALID_DATAHTTP 400
- The given trigger is not valid.
  Resolution: Ensure that the value provided for the type key is valid for the specified module. Refer to the Get Workflow Configurations API to know which trigger types are supported for each module.
- The value given seems to be invalid.
  Resolution: Check the details key in the response to identify which field has the invalid value and update it accordingly.
- Invalid sequence number is given
  Resolution: Ensure that sequence_number values are unique and follow a sequential order starting from 1. You will get this error if the same value is repeated or if the sequence is broken.
- Data type not supported
  Resolution: The Convert action is not supported in scheduled actions. Remove the Convert action from the scheduled_actions array and try again.
- Rule Name should not contain the following special characters: #, %, ^, &, *, (, )
  Resolution: Remove any unsupported special characters from the rule name. Only use alphanumeric characters, spaces, or underscores.
- Active Rules Limit Exceeds
  Resolution: You have reached the maximum limit of active workflow rules for this module. Deactivate or delete existing rules to create new ones.
- Total Rules Limit Exceeds
  Resolution: You have reached the maximum limit of workflow rules for this module. Delete existing rules to create new ones.
- The length of name has exceeded the limit
  Resolution: The rule name must not exceed 100 characters. Shorten the name and try again.
- Invalid action ID
  Resolution: The id provided for the action in the input JSON is not valid. Verify and update it with a valid value.
AMBIGUITY_DURING_PROCESSINGHTTP 400
The given criteria is part of another condition
Resolution: Ensure that each criteria block under conditions is unique and not repeated across multiple condition objects. Check the details section in the response to identify the duplicate usage.
AMBIGUITY_DURING_PROCESSINGHTTP 400
This error may occur due to conflicting configurations in your workflow rule
Resolution:
1. Define a valid condition block when using the convert action. The convert action cannot be used without specifying conditions.
2. Do not repeat in execute_when.details when using the convert action. The convert action is only supported for non-repeating triggers.
3. Verify valid combinations of triggers and supported actions, use the Get Workflow Configuration API.
LIMIT_EXCEEDEDHTTP 400
- Actions limit exceeded
  Resolution: You have exceeded the maximum number of actions allowed for a particular type. Check the details key in the response for the api_name of the action type and the limit value to know the allowed maximum.
- The Limit of criteria fields is exceeded
  Resolution: You can specify a maximum of five fields in the trigger criteria. Reduce the number of fields and try again.
- The Limit of selected section ids exceeded
  Resolution: Only a maximum of 10 sections can be specified in the trigger criteria. Ensure that no more than 10 section IDs are listed in the section_ids array.
- Workflow condition limit exceeded
  Resolution: A maximum of 10 conditions can be added to a workflow rule. Remove extra conditions and try again.
- Fields limit exceeded
  Resolution: Only a maximum of 25 fields can be checked in the condition criteria. Remove any additional fields and try again.
DUPLICATE_DATAHTTP 400
Duplicate action not allowed
Resolution: The same action has been added more than once in the workflow condition. Remove the duplicate and ensure each action within a condition is unique.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to create a Workflow rule. Create a new token with valid scope. Refer to the Scope section for more details.
NO_PERMISSIONHTTP 403
Permission denied for the resource
Resolution: You do not have permission to perform this action. Only users with Manage Workflow permission can perform this action.
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{
    "workflow_rules": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "3733973000000745029"
            },
            "message": "workflow created",
            "status": "success"
        }
    ]
}