Create a Cadence

Represents the name of the cadence. Accepts alphanumeric characters. Maximum 100 characters. Must not contain #, %, or ^. Must be unique within the organization.

Represents the API name and ID of the module for which you want to create the cadence. Use the Get Modules API to get the API name and ID of the module.

Represents the type of the cadence. Possible values are:

• custom_view: To create a cadence for a specific custom view.
• manual_enrollment: To create a cadence for manually enrolling records.

The unique ID of the custom view you want to create the cadence for. Use the Get Custom View API to get the ID of the custom view.

Each JSON object in this array represents the frequency of execution of the cadence, unenrollment properties, and the follow up criteria.

Represents an ordered list of automated actions like tasks, emails, calls that you want to trigger within the cadence. Follow-ups are linked via reference_id and parent_follow_up.

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.

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.

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.

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.

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.

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.

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.

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.

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.

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.

JSON path:$.cadences[0].follow_ups[n].action.details.layout.id /

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.

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.

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.

The value provided for unenroll_date does not match the required date format.
Resolution: Provide the unenroll_date value in YYYY-MM-DD format (for example, 2026-10-29).

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.

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.

One or more of the mandatory fields such as name, module, or type are missing from the request body.
Resolution: Include all three fields in the request body. Refer to the Request JSON Keys section for the full list of mandatory parameters.

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.

One or more mandatory fields are missing inside a follow_ups object: 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.

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.

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.

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 missing 
Resolution: The execute_after field is required when triggers field is provided. Provide execute_after field.

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.

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.

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.

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.

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.

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.

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.

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).

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.

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 created follow-ups in the same request, e.g. Followup_1) or the id (for existing follow-ups) inside the parent_follow_up object.

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.

JSON path:$.cadences[0].execution_details.unenroll_properties[n].criteria.group /

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.

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.

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.

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.

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.

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.

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.

The number of follow-ups in the cadence exceeds the allowed maximum.
Resolution: A maximum of 70 follow-ups can be created per cadence. Remove or consolidate follow-up steps to stay within this limit.

The number of cadences for the specified module has reached its maximum limit.
Resolution: A maximum of 60 cadences can be created per module. Delete unused cadences from this module before creating a new one.

The total number of cadences across your organization has reached its maximum limit.
Resolution: A maximum of 150 cadences can exist across the entire organization. Delete unused cadences from any module before creating new ones.

The request method is incorrect.
Resolution: Use the HTTP POST method to make this API call. Any other request method will result in this error.

You do not have sufficient permission to add a cadence.
Resolution: Contact your system administrator.

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.CREATE or ZohoCRM.settings.cadences.ALL.

You do not have the Crm_Implied_Manage_Cadences permission.
Resolution: Contact your system administrator.

The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the Request URL section for the right URL.

Unexpected and unhandled exception in the server. 
Resolution: Contact the support team at support@zohocrm.com.