Update a Cadence

Purpose

Use this API to update an existing cadence in your Zoho CRM organization. You can update the cadence's name or description, add or modify follow-up steps, and update unenrollment conditions. Note that when you edit a published cadence, a draft one will be created (draft_cadence key).

Endpoints

PUT /settings/automation/cadences
PUT /settings/automation/cadences/{cadence_ID}

Request Details

Request URL

{api-domain}/crm/{version}/settings/automation/cadences
To update a specific cadence: {api-domain}/crm/{version}/settings/automation/cadences/{cadence_id}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Sample Request

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

Request JSON to update name or description

idstring, mandatory
Represents the ID of the cadence you want to update. Include the ID in the body only when you have not specified in the request URL.
namestring, optional
Represents the updated name of the cadence. Accepts alphanumeric characters. Maximum 100 characters. Must not contain #, %, or ^. Must be unique within the organization.
descriptionstring, optional
Represents the updated description for the cadence. Maximum 500 characters.

Sample input to update name or description

Copied{
    "cadences": [
        {
            "name": "cadence3New",
            "description": "descriptionNew"
        }
            
    ]
}

Request JSON to add a new follow-up

follow_ups JSON array, mandatory
Contains the new follow up steps to add to the cadence.
- parent_follow_up JSON object, optional
  References the existing follow up that this new step depends on. Must include either id or reference_id of the existing follow up.
reference_id string, mandatory
Temporary identifier for this new follow up (e.g., {{FollowUp3}}). Use this to reference it as a parent within the same request.
action JSON object, mandatory
The activity to perform at this follow-up step.
- type string, mandatory
  The activity type. Accepted values are tasks, email_notifications, schedule_call, whatsapp_message_notification.
- id string, optional
  ID of that pre-configured action.
  Note
  - When action.type is schedule_call, id is not applicable; include the details object instead. Refer to Request JSON section of create cadences for more details.

Sample input to add a new follow-up

Copied{
    "cadences": [
        {
            "follow_ups": [{
                "parent_follow_up": {
                    "id": "111112000000092009"
                },
                "reference_id": "{{FollowUp3}}",
                "action": {
                    "type": "email_notifications",
                    "id": "111112000000092062"
                }
            }]
        }
    ]
}

Request JSON to update an existing follow-up

triggersJSON array, optional
Outcome status(es) of the parent follow-up that trigger this step (e.g., ["Completed"]).
execute_afterJSON object, conditional
Contains unit (integer) and period. Accepted values are minutes, hours, business_hours, days, business_days, or months.

Sample input to update an existing follow-up

Copied{
    "cadences": [
        {
            "triggers": [
                "Completed"
            ],
            "execute_after": {
                "unit": 10,
                "period": "minutes"
            }
        }
    ]
}

Request JSON to update un-enrollment conditions

execution_detailsJSON object, mandatory
- unenroll_propertiesJSON array, mandatory
  Updated list of un-enrollment conditions. Each item in the array represents one condition. Maximum of one item per type value. Possible values for the type key are:
  - typestring, mandatory
    The un-enrollment trigger type. Accepted values are automatic_unenroll, end_date, criteria, followup_criteria.
  - detailsJSON object, conditional
    Required for all type values except automatic_unenroll. Structure varies by type:
    end_date - Contains unenroll_date (string, format: YYYY-MM-DD).
    criteria - contains a criteria object with field.api_name, comparator, and value.
    followup_criteria — contains type (accepted values: tasks, schedule_call, email_notifications, whatsapp_message_notification) and a nested details object with criteria, specific (boolean), and state (null or object with id). When specific is false, state must be null, when specific is true, state must contain the ID of the specific follow-up. For more details about each of these keys, refer to the Create a Cadence API.
    - specificBoolean, mandatory
      Applies only to followup_criteria type. Indicates whether the un-enrollment condition applies to a specific follow-up (true) or any follow-up of the given type (false).
    - detailsJSON object, optional
      Applies only to followup_criteria type. When specific is true, provide an object with the ID of the target follow-up. When specific is false, set to null.

Note

To delete a follow-up, include its id and set _delete to null.

When you edit a published cadence, the first save creates a draft. The response includes a draft_cadence ID—use this ID for all subsequent edits, then call publish once your changes are complete.

Sample input to update un-enrolment conditions

Copied{
    "cadences": [
        {
            "execution_details": {
                "unenroll_properties": [
                    {
                        "type": "followup_criteria",
                        "details": {
                            "type": "tasks",
                            "details": {
                                "criteria": {
                                    "field": {
                                        "api_name": "Subject",
                                        "id": "111112000000004066"
                                    },
                                    "comparator": "equal",
                                    "value": "tested"
                                },
                                "specific": true,
                                "state": {
                                    "id": "111112000000092009"
                                }
                            }
                        }
                    }
                ]
            }
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
The name field contains one or more disallowed characters. Special characters #, %, and ^, as well as emoji, are not permitted.
Resolution: Remove all special characters (#, %, ^) and emoji from the cadence name. Use only alphanumeric characters and supported punctuation.
INVALID_DATAHTTP 400
The value provided for name or description exceeds the allowed character limit.
Resolution: Ensure the name does not exceed 100 characters and the description does not exceed 500 characters. Check the maximum_length key in the error response for the exact limit that was breached.
INVALID_DATAHTTP 400
The value provided for the type field is not supported.
Resolution: Use one of the supported values for type: custom_view or manual_enrollment. Refer to the supported_values key in the error response for the valid options.
INVALID_DATAHTTP 400
The value provided for execute_every.period is not a supported option.
Resolution: Use one of the supported values for period: immediately, hours, days, or weeks. Refer to the supported_values key in the error response.
INVALID_DATAHTTP 400
The value provided for execute_every.unit is outside the permitted range.
Resolution: Provide a valid integer for unit based on the selected period: the accepted range is 1 to 99.
INVALID_DATAHTTP 400
The value provided for reference_id does not follow the required format.
Resolution: Use the format {{Followup_<count>}} where <count> is a sequential integer starting from 1 (for example, Followup_1, Followup_2). This value must match the reference_id assigned to another follow-up in the same request when used inside parent_follow_up.
INVALID_DATAHTTP 400
The value provided for action.type is not a supported option.
Resolution: Use one of the supported values for action.type: tasks, email_notifications, schedule_call, or whatsapp_message_notification. Refer to the supported_values key in the error response.
INVALID_DATAHTTP 400
The value provided for action.id is not a valid action ID.
Resolution: Verify that the id references an existing action template. Ensure the action belongs to the correct type (tasks, email_notifications, or whatsapp_message_notification) and has not been deleted.
INVALID_DATAHTTP 400
The specified action.id is already associated with another cadence, or the same ID appears more than once in the request.
Resolution: Each action can be linked to only one follow-up. Use a different action ID that is not already in use, or remove the duplicate entry from the request.
INVALID_DATAHTTP 400
The id provided for action.details.layout or action.details.module is not valid.
Resolution: Verify the layout ID using the Layouts Metadata API and the module ID using the Get Modules API. Ensure the IDs referenced belong to the correct module and have not been deleted.
INVALID_DATAHTTP 400
The value provided for type inside a field_mappings entry is not supported.
Resolution: Use one of the supported values for field mapping type: static, reference, time_computed, execution_time, or merge_field. Refer to the supported_values key in the error response.
INVALID_DATAHTTP 400
The value provided for execute_after.period is not a supported option.
Resolution: Use one of the supported values for execute_after.period: minutes, hours, business_hours, days, business_days, or months.
INVALID_DATAHTTP 400
The value provided for execute_after.unit is outside the permitted range for the selected period.
Resolution: Provide a valid integer for unit based on the execute_after.period selected: the accepted range is 1 to 99.
INVALID_DATAHTTP 400
The value provided for unenroll_date does not match the required date format.
Resolution: Provide the unenroll_date value in YYYY-MM-DD format.
INVALID_DATAHTTP 400
The follow-up ID provided in details.state.id is not valid.
Resolution: Provide the ID of an existing follow-up that belongs to this cadence. Use the Get Cadences API to retrieve valid follow-up IDs.
INVALID_DATAHTTP 400
The value provided for type in an unenroll_properties entry is not supported.
Resolution: Use one of the supported values for unenroll_properties[].type: automatic_unenroll, end_date, criteria, or followup_criteria.
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory fields are missing from the request body.
Resolution: Include all required fields in the request body. Refer to the Request JSON Keys section for the full list of mandatory parameters. Refer to the json_path in the error response to identify the exact missing field.
MANDATORY_NOT_FOUNDHTTP 400
The mandatory field period is missing from the execute_every object inside execution_details.
Resolution: Include the period key in the execute_every object. The supported values are immediately, hours, days, and weeks.
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory fields are missing inside a follow_ups array: reference_id, parent_follow_up (for follow-ups beyond the first), action, or action.type.
Resolution: Ensure every follow-up entry includes reference_id, action, and action.type. All follow-ups after the first must also include parent_follow_up. Refer to the json_path in the error response to identify the exact missing field.
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory fields are missing from the action.details object required for a schedule_call action: layout, module, field_mappings, or one of the field mapping sub-keys (field, type, value).
Resolution: Provide all required fields in the action.details object:
- layout — the ID of the call layout.
- module — the ID of the module.
- field_mappings — an array of field mapping objects, each containing field, type, and value.
Refer to the json_path in the error response to identify the exact missing field.
MANDATORY_NOT_FOUNDHTTP 400
The mandatory fields unit and/or period are missing from the execute_after object in a follow-up.
Resolution: Include both unit and period in the execute_after object. Refer to the json_path in the error response to identify the exact missing field.
DUPLICATE_DATAHTTP 400
A cadence with the specified name already exists in your organization.
Resolution: Provide a unique name for the cadence. Use the Get Cadences API to verify that the name is not already in use.
DEPENDENT_FIELD_MISSINGHTTP 400
Dependent Field missing
Resolution: The execute_after field is required when triggers field is provided. Provide execute_after field.
DEPENDENT_FIELD_MISSINGHTTP 400
The custom_view field is required when type is set to custom_view, but it was not included in the request.
Resolution: Include the custom_view object with its id when the cadence type is custom_view. Use the Get Custom View API to obtain the correct ID.
DEPENDENT_FIELD_MISSINGHTTP 400
The unit field is required inside execute_every when period is not immediately, but it was not provided.
Resolution: Include the unit key in the execute_every object whenever period is hours, days, or weeks. The value must be an integer between 1 and 99.
DEPENDENT_FIELD_MISSINGHTTP 400
A required dependent field for the specified action.type is missing: either id or details.
Resolution: Provide the correct dependent field based on the action.type value:
- When action.type is tasks, email_notifications, or whatsapp_message_notification — include the id of the relevant action template.
- When action.type is schedule_call - include the details object instead.
DEPENDENT_FIELD_MISSINGHTTP 400
The details object is required for the specified unenroll_properties.type but was not provided.
Resolution: Include the details object for all unenroll_properties entries where type is end_date, criteria, or followup_criteria.
DEPENDENT_FIELD_MISSINGHTTP 400
The unenroll_date field is required inside details when unenroll_properties.type is end_date, but it was not included.
Resolution: Add the unenroll_date key to the details object when type is end_date. The date must be in YYYY-MM-DD format.
DEPENDENT_FIELD_MISSINGHTTP 400
The criteria field is required inside details when unenroll_properties.type is criteria, but it was not included.
Resolution: Add the criteria key to the details object when type is criteria. The criteria object must contain at least one of group or field.
DEPENDENT_FIELD_MISSINGHTTP 400
The nested details object (inside unenroll_properties.details) is required when unenroll_properties.type is followup_criteria, but it was not provided.
Resolution: Include the inner details object inside unenroll_properties.details when type is followup_criteria. This object must specify the follow-up action type, whether to match a specific follow-up state (specific), the target state (state), and the criteria.
DEPENDENT_FIELD_MISSINGHTTP 400
The specific (boolean) and/or state (JSON object) fields are missing from the nested details object when unenroll_properties.type is followup_criteria.
Resolution: Include both specific and state in the inner details object. Set specific to true to match a specific follow-up state (and provide state.id), or to false to match any state (in which case state should be omitted or null).
DEPENDENT_FIELD_MISSINGHTTP 400
The criteria field is required inside the nested details.details object when unenroll_properties.type is followup_criteria, but it was not provided.
Resolution: Add the criteria key to the inner details object. The criteria object must define the conditions (using group or field) under which the record should be unenrolled from the cadence.
EXPECTED_FIELD_MISSINGHTTP 400
The parent_follow_up object is missing at least one identifier. Either reference_id or id must be specified.
Resolution: Provide either the reference_id (for newly added follow-ups in the same request, e.g. Followup_1) or the id (for existing follow-ups) inside the parent_follow_up object.
EXPECTED_FIELD_MISSINGHTTP 400
The criteria object inside unenroll_properties.details is missing both group and field.
Resolution: Provide at least one of group or field inside the criteria object to define the unenrollment condition.
EXPECTED_DEPENDENT_FIELD_MISSINGHTTP 400
A follow-up has a parent_follow_up.reference_id defined but triggers was not included.
Resolution: When a follow-up references a parent via reference_id, provide triggers.
DEPENDENT_MISMATCHHTTP 400
One or more values in the triggers array are not valid for the parent follow-up's action type.
Resolution: Use only trigger values that are applicable to the parent follow-up's action type. For example, task actions support triggers such as Not Started, Deferred, In Progress, Completed, and Waiting on someone else. Refer to the supported_values key in the error response for the full list valid for the specific action type.
DEPENDENT_MISMATCHHTTP 400
The type value inside the nested details object is not valid for a followup_criteria unenroll property.
Resolution: Use one of the supported values for details.type within a followup_criteria entry: tasks, schedule_call, email_notifications, or whatsapp_message_notification.
AMBIGUITY_DURING_PROCESSINGHTTP 400
The same trigger value appears more than once in the triggers array of a single follow-up.
Resolution: Remove duplicate entries from the triggers array. Each trigger value must be unique within a single follow-up's triggers array.
AMBIGUITY_DURING_PROCESSINGHTTP 400
There is a conflict between the values of specific and state in the nested details object of a followup_criteria unenroll property.
Resolution: Ensure the two fields are consistent:
- When specific is true — provide the state object with a valid follow-up id.
- When specific is false — omit the state field or set it to null; do not include a state object alongside a false value.
ALREADY_USEDHTTP 400
A trigger value has already been used by a sibling follow-up that shares the same parent follow-up and cannot be reused.
Resolution: Each trigger value can be assigned to only one child follow-up per parent. Review the exists_in.json_path in the error response to see which follow-up already uses this trigger, and assign a different, unused trigger value to the current follow-up.
LIMIT_EXCEEDEDHTTP 400
A specific unenroll_properties type has been specified more than the permitted number of times.
Resolution: Each unenroll type (except followup_criteria) may appear only once in the unenroll_properties array. Review the array and remove duplicate type entries.
LIMIT_EXCEEDEDHTTP 400
Adding the new follow-ups would exceed the maximum number allowed per cadence.
Resolution: A maximum of 70 follow-ups can exist per cadence. Remove or consolidate existing follow-up steps before adding new ones.
NOT_ALLOWEDHTTP 400
You attempted to delete a follow-up that is not the last follow-up in the cadence chain. Only the last follow-up — one that has no child follow-ups — can be deleted.
Resolution: Delete follow-ups in reverse order, starting from the last follow-up (one with no children). To delete an intermediate follow-up, first delete all follow-ups that depend on it.
INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP PUT method to make this API call. Any other request method will result in this error.
AUTHORIZATION_FAILEDHTTP 400
You do not have sufficient permission to update a cadence.
Resolution: Contact your system administrator.
OAUTH_SCOPE_MISMATCHHTTP 401
The access token you have used to make this API call does not have the required scope.
Resolution: Generate a new access token with the scope ZohoCRM.settings.cadences.UPDATE or ZohoCRM.settings.cadences.ALL.
NO_PERMISSIONHTTP 403
You do not have the Crm_Implied_Manage_Cadences permission.
Resolution: Contact your system administrator.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the Request URL section for the right URL.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "cadences": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "554023000006316030"
            },
            "message": "Cadences updated successfully",
            "status": "success"
        }
    ]
}