Configure Workflow Rule
Purpose
To configure a Workflow rule in Zoho CRM.
Endpoints
- POST /settings/automation/workflow_rules
Request Details
Request URL
{api-domain}/crm/{version}/settings/automation/workflow_rules
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
ZohoCRM.settings.workflow_rules.ALL
(or)
ZohoCRM.settings.workflow_rules.CREATE
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/workflow_rules"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @createworkflow.json
-X POST
Input JSON
The request body must contain a workflow_rules array. You can include only one object in this array per request.
- execute_whenJSON object, mandatory
Defines the conditions under which the workflow rule will be executed.
- typestring, mandatory
The type of event that triggers the workflow.
Possible values:
Module/Context Possible Values Record action create, edit, create_or_edit, delete, field_update, rollup_summary_update, section_update, date_or_datetime, score_increase, score_update, score_decrease, recommendation Field-Specific triggers field_update 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 - detailsJSON object, optional
Contains details about the trigger.
- repeatboolean, mandatory if the trigger value is edit or create_or_edit.
Indicates that the workflow should be repeated every time a record is updated.
- trigger_moduleJSON object, mandatory if the trigger value is edit or create_or_edit.
Details of the related module that triggers the rule. For instance, if you want to trigger the Workflow based on records notes, add the details of Notes module here. The JSON object contains the API name and the ID of the module.
- moduleJSON object, mandatory
Specify the module to which the workflow rule applies.
- namestring, mandatory
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
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, mandatory
An array of condition objects that define the criteria for executing the actions.
- sequence_numberinteger, mandatory
Represents the execution order for the criteria. The index starts from 1.
- criteria_detailsJSON object, mandatory
Specify the conditions a record must meet for the workflow rule to trigger. Set this to null to apply the rule to all records in the module.
- criteriaJSON object, optional
Specifies which records the rule should apply to. 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, mandatory
The list of Instant Actions to execute immediately when condition is met.
- actionsJSON array, mandatory
An array of action objects, each containing the following:
- typestring, mandatory
Specify the type of action (e.g., field_updates, email_notifications, tasks, add_tags, create_record, etc.). Refer to the Actions section for more details on the different possible action types.
- 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. See the Actions section for details on which API to use for each type. - related_detailsJSON object, mandatory
Additional information depending on action type (e.g., follow-ups for tasks, tags for add_tags, etc.). Refer to the Actions section for more details.
- 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 : business_hours, hours, business_days, days, minutes, weeks, months, years - unitinteger, mandatory
The number of time units to wait before executing the scheduled action.
- actionsJSON array, mandatory
The list of scheduled actions.
- 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. See the Actions section for details on which API to use for each type. - related_detailsJSON object, mandatory
Additional information depending on action type (e.g., follow-ups for tasks, tags for add_tags, etc.). Refer to the Actions section for more details.
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 name 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.
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Emails",
"id": "4876876000000014163"
}
},
"type": "email_received"
},
"module": {
"api_name": "Emails"
},
"name": "Testing Emails Trigger",
"description": "Testing Emails Tigger",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"id": "4876876000010792012",
"type": "email_notifications"
}
]
},
"scheduled_actions": [
{
"execute_after": {
"period": "business_days",
"unit": 1
},
"actions": [
{
"id": "4876876000000329771",
"type": "tasks"
}
]
}
],
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": {
"group_operator": "OR",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Lead_Source",
"id": "4876876000000002609"
},
"type": "value",
"value": [
"Employee Referral",
"Partner"
]
},
{
"comparator": "greater_than",
"field": {
"api_name": "Final_Score",
"id": "4876876000002752001"
},
"type": "value",
"value": "15"
}
]
},
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
}
},
"criteria": {
"comparator": "contains",
"field": {
"api_name": "Subject",
"id": "4876876000000014189"
},
"type": "value",
"value": "Urgent"
}
}
},
{
"sequence_number": 2,
"instant_actions": {
"actions": [
{
"details": {
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
}
},
"id": "4876876000011017020",
"type": "field_updates"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": null,
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
}
},
"criteria": {
"group_operator": "AND",
"group": [
{
"comparator": "contains",
"field": {
"api_name": "Attachment_Name",
"id": "4876876000000203005"
},
"type": "value",
"value": "contract"
},
{
"comparator": "contains",
"field": {
"api_name": "Subject",
"id": "4876876000000014189"
},
"type": "value",
"value": "success"
}
]
}
}
}
]
}
]
}The value of execute_when.type key in the input JSON depends on the type of trigger. The supported values vary based on the type of module or trigger context.
1. Triggers
1.1 Record Actions Triggers
Possible values for execute_when.type
- create : To trigger the Workflow rule when a new record is created in the selected module
- create_or_edit : To trigger the Workflow rule when a new record is created, or an existing record is edited
- edit : To trigger the Workflow rule when an existing record is edited
- delete : To trigger the Workflow rule when a record is deleted
Sample Input for Record Action trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"repeat": true
},
"type": "create_or_edit"
},
"module": {
"api_name": "Leads"
},
"name": "Testing Create or Edit Tigger",
"description": "Testing Edit Tigger",
"conditions": [
{
"sequence_number": 1,
"criteria_details": {
"criteria": {
"group_operator": "and",
"group": [
{
"group_operator": "and",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Annual_Revenue"
},
"value": "${NOTEMPTY}"
},
{
"comparator": "equal",
"field": {
"api_name": "Phone"
},
"value": "${NOTEMPTY}"
}
]
}
]
}
},
"instant_actions": {
"actions": [
{
"id": "4876876000011017020",
"type": "field_updates"
},
{
"id": "4876876000010792012",
"type": "email_notifications"
}
]
}
}
]
}
]
}1.2 Field-Specific Triggers
When using field-specific triggers, the Workflow rule will be triggered based on specific field-level changes. The value of the execute_when.type key determines the type of field-specific trigger, and additional configuration must be specified in the execute_when.details object.
Possible values for execute_when.type:
| Value | Description |
|---|---|
| field_update | Triggers the Workflow rule when specified fields are updated. |
| rollup_summary_update | Triggers the Workflow rule when rollup summary fields are recalculated. |
| section_update | Triggers the Workflow rule when any field in specified sections is updated. |
Additional JSON keys in execute_when.details, when execute_when.type is field_update:
- criteriaJSON object, mandatory
Defines the field change conditions to evaluate.
- group_operatorJSON object, mandatory
Logical operator for combining conditions.
Possible values: AND, OR
- groupJSON array, mandatory
List of field conditions
- comparatorstring, mandatory
Comparison operator.
Possible values : equal, not_equal, contains, starts_with, greater_than, less_than, is_empty
- fieldJSON object, mandatory
The details of the field whose value is being compared.
- valuestring, mandatory
The value to compare with. Use ${EMPTY} to check for empty fields.
- match_allBoolean, mandatory
Specify whether all the given criteria must match for the Workflow rule to be triggered.
Possible values :
true - All criteria must match for the Workflow to trigger.
false - Any criteria match is sufficient for the Workflow to trigger.
Additional JSON keys in execute_when.details, when execute_when.type is rollup_summary_update:
- criteriaJSON Object, mandatory
Define the condition to evaluate on the rollup summary field. The object must include field, comparator and value.
- fieldJSON Object, mandatory
Specify the API name and the unique ID of the roll up summary field.
- comparatorstring, mandatory
Specify the comparison operator to evaluate the field value.
- valuestring, mandatory
Specify the value to compare against.
Additional JSON keys in execute_when.details, when execute_when.type is section_update:
- section_idsJSON array, mandatory
Specify the unique IDs of the sections whose fields trigger the workflow.
Sample Input for Field Update Trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"criteria": {
"group_operator": "AND", //all the criteria should be satisfied for the rule to be triggered
"group": [
{
"comparator": "greater_equal",
"field": {
"api_name": "Annual_Revenue",
"id": "4876876000000002617"
},
"type": "value",
"value": "100000"
},
{
"comparator": "${ANYVALUE}", //triggers the workflow when the field is updated to any value.
"field": {
"api_name": "Custom_Field",
"id": "4876876000003810007"
},
"value": "${ANYVALUE}"
}
]
},
"repeat": false,
"match_all": true //all the criteria should be satisfied for the rule to be triggered
},
"type": "field_update"
},
"module": {
"api_name": "Leads"
},
"name": "Testing Edit Specific Field Tigger",
"description": "Testing Edit Tigger",
"conditions": [
{
"sequence_number": 1,
"criteria_details": {
"criteria": {
"group_operator": "and",
"group": [
{
"group_operator": "and",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Annual_Revenue"
},
"value": "${NOTEMPTY}"
},
{
"comparator": "equal",
"field": {
"api_name": "Phone"
},
"value": "${NOTEMPTY}"
}
]
}
]
}
},
"instant_actions": {
"actions": [
{
"id": "4876876000011017020",
"type": "field_updates"
},
{
"id": "4876876000010792012",
"type": "email_notifications"
}
]
}
}
]
}
]
}Sample Input for Rollup Summary field update trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"criteria": {
"comparator": "${ANYVALUE}",
"field": {
"api_name": "Rollup_Summary",
"id": "4876876000010911001"
},
"value": "${ANYVALUE}"
},
"repeat": true,
"match_all": false
},
"type": "rollup_summary_update"
},
"module": {
"api_name": "Leads"
},
"name": "Testing Rollup Summary field Trigger",
"description": "Testing",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"name": "EmailContactRoles",
"id": "4876876000011037121",
"type": "functions"
}
]
}
}
]
}
]
}Sample Input for Section update trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"section_ids": [
"4876876000000967048",
"4876876000000209002"
],
"repeat": true
},
"type": "section_update"
},
"module": {
"api_name": "Leads"
},
"name": "Testing Edit Specific Section Tigger",
"description": "Testing Edit Tigger",
"conditions": [
{
"sequence_number": 1,
"criteria_details": {
"criteria": {
"group_operator": "and",
"group": [
{
"group_operator": "and",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Annual_Revenue"
},
"value": "${NOTEMPTY}"
},
{
"comparator": "equal",
"field": {
"api_name": "Phone"
},
"value": "${NOTEMPTY}"
}
]
}
]
}
},
"instant_actions": {
"actions": [
{
"id": "4876876000011017020",
"type": "field_updates"
},
{
"id": "4876876000010792012",
"type": "email_notifications"
}
]
}
}
]
}
]
}1.3 Date and Datetime triggers
Possible values for execute_when.type:
date_or_datetime : To trigger the Workflow rule based on date or datetime fields. The execute_when.details JSON object should have the details of the field based on which the Workflow rule should be triggered.
Additional JSON keys in execute_when.details:
- fieldJSON object, mandatory
The details of the date or datetime field, based on which the Workflow rule should be triggered. Specify the field API name and the field ID.
- unitstring, mandatory
The number of time units after which the Workflow rule should be triggered. Use negative values to trigger the Workflow rule before and positive values to trigger after the specified time.
- periodstring, mandatory
The time unit.
Possible values : b_days, days, weeks, months, years - execute_atstring, mandatory
The exact time of day at which the workflow will trigger. Specify the time in ISO 8601 format.
- recur_cyclestring, mandatory
The recurrence period for the Workflow rule.
Possible values: once, monthly, yearly - repeatBoolean, mandatory
Specify whether the workflow should be triggered each time the date/datetime field is updated.
Sample input for date/datetime based trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"unit": -1, //to trigger the workflow one week BEFORE the date
"period": "weeks",
"field": {
"api_name": "Date_1",
"id": "4876876000003643015"
},
"recur_cycle": "yearly",
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"repeat": false,
"execute_at": "08:00:00+05:30"
},
"type": "date_or_datetime"
},
"module": {
"api_name": "Leads"
},
"name": "Testing Datetime Trigger",
"description": "Testing Datetime Tigger",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"name": "F1",
"details": {
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
}
},
"id": "4876876000008304003",
"type": "field_updates"
},
{
"id": "4876876000010792001",
"type": "email_notifications"
}
]
},
"scheduled_actions": [
{
"execute_after": {
"period": "business_days",
"unit": 3
},
"actions": [
{
"id": "4876876000010792001",
"type": "email_notifications"
}
]
}
]
}
]
}
]
}1.4 Scoring Rule based triggers
You can configure to trigger the Workflow rule when the record score changes for any scoring rule, or specific scoring rules. To trigger based specific scoring rules, specify the details of the rules in the execute_when.details.rules JSON array.
Possible values for execute_when.type:
- score_increase : To trigger the Workflow rule when the score increases.
- score_decrease : To trigger the Workflow rule when the score decreases.
- score_update : To trigger the Workflow rule when the score changes (increase or decrease).
Additional JSON keys in execute_when.details:
- typestring, mandatory
Represents whether the Workflow rule should be triggered based on any scoring rule or specific scoring rules.
Possible values:
- All_Rules : The Workflow rule should be triggered for change in score for any scoring rule.
- Selective_Rules : The Workflow rule should be triggered for change in specific scoring rules. The details of these rules should be specified in the execute_when.details.rules JSON array.
- rulesJSON array, mandatory if the value of execute_when.details.type key is Selective_Rules
Specify the unique IDs of all the scoring rules, based on which you want to trigger the Workflow rule.
Sample Input for Scoring Rule Trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"type": "All_Rules"
},
"type": "score_increase"
},
"module": {
"api_name": "Leads"
},
"name": "Testing Scoring Rule Trigger",
"description": "Testing Scoring Rule Tigger",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"id": "4876876000000329765",
"type": "tasks"
},
{
"name": "P1",
"details": {
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"over_write": false,
"tags": [
{
"name": "P1",
"id": "4876876000011037076",
"color_code": "#F17574"
}
]
},
"type": "add_tags"
}
]
}
}
]
}
]
}1.5 Triggers - Email module
You can configure the Workflow rule to trigger when an email is received, sent, opened, clicked, bounced, replied to, or when a time condition is met. Specify the Emails module as the trigger module in the execute_when.details.trigger_module JSON object.
Possible values for execute_when.type:
| Value | Description |
|---|---|
| On record actions | |
| email_received | To trigger the Workflow rule when an email is received. |
| mail_sent | To trigger the Workflow rule when an email is sent. |
| mail_sent_clicked | To trigger the Workflow rule when an email is clicked. |
| mail_sent_opened | To trigger the Workflow rule when a sent email is opened. |
| mail_sent_bounced | To trigger the Workflow rule when a sent email bounces. |
| mail_sent_replied | To trigger the Workflow rule when a sent email is replied to. |
| On time conditions | |
| email_received_notreplied | To trigger the Workflow rule when an incoming email is not replied to within a time period. |
| email_received_opened_notreplied | To trigger the Workflow rule when an incoming email is opened but not replied to within a time period. |
| mail_sent_replied_within | To trigger the Workflow rule when a sent mail is replied to within the specified time. |
| mail_sent_opened_notreplied | To trigger the Workflow rule when a sent mail is opened but not replied to within the specified time. |
| mail_sent_notreplied | To trigger the Workflow rule when a sent mail is not replied to within the specified time. |
| mail_sent_notopened | To trigger the Workflow rule when a sent mail is not opened within the specified time. |
For all of the above trigger types, the following keys apply in the execute_when.details JSON object:
- trigger_moduleJSON Object, mandatory
Specify the Emails module.
- periodString, mandatory for time triggers
The time unit.
Possible values: minutes, hours, days, b_days, b_hours - unitInteger, mandatory for time triggers
Number of time units after which the workflow should trigger.
Sample Input for Email module triggers
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Emails",
"id": "4876876000000014163"
}
},
"type": "email_received"
},
"module": {
"api_name": "Emails"
},
"name": "Testing Emails Trigger",
"description": "Testing Emails Tigger",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"id": "4876876000010792012",
"type": "email_notifications"
}
]
},
"scheduled_actions": [
{
"execute_after": {
"period": "business_days",
"unit": 1
},
"actions": [
{
"id": "4876876000000329771",
"type": "tasks"
}
]
}
],
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": {
"group_operator": "OR",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Lead_Source",
"id": "4876876000000002609"
},
"type": "value",
"value": [
"Employee Referral",
"Partner"
]
},
{
"comparator": "greater_than",
"field": {
"api_name": "Final_Score",
"id": "4876876000002752001"
},
"type": "value",
"value": "15"
}
]
},
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
}
},
"criteria": {
"comparator": "contains",
"field": {
"api_name": "Subject",
"id": "4876876000000014189"
},
"type": "value",
"value": "Urgent"
}
}
},
{
"sequence_number": 2,
"instant_actions": {
"actions": [
{
"details": {
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
}
},
"id": "4876876000011017020",
"type": "field_updates"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": null,
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
}
},
"criteria": {
"group_operator": "AND",
"group": [
{
"comparator": "contains",
"field": {
"api_name": "Attachment_Name",
"id": "4876876000000203005"
},
"type": "value",
"value": "contract"
},
{
"comparator": "contains",
"field": {
"api_name": "Subject",
"id": "4876876000000014189"
},
"type": "value",
"value": "success"
}
]
}
}
}
]
}
]
}1.6 Triggers - Calls module
You can configure the Workflow rule to trigger on record actions, field updates, date/time field updates, and Notes updates in the Calls module. Specify the Calls module in the execute_when.details.trigger_module JSON object.
Note:
Along with the special triggers as described below, you can also trigger Workflow rules based on any date or datetime fields in the Calls module.
Possible values for execute_when.type:
On record action:
| Value | Description |
|---|---|
| incoming_call_ring | To trigger the Workflow rule when an incoming call rings. |
| incoming_call_start | To trigger the Workflow rule when an incoming call starts. |
| incoming_call_edit | To trigger the Workflow rule when an incoming call record is edited. |
| incoming_call_createedit | To trigger the Workflow rule when an incoming call record is created or edited. |
| scheduled_call_edit | To trigger the Workflow rule when a scheduled call is edited. |
| scheduled_call_createedit | To trigger the Workflow rule when a scheduled call is created or edited. |
| outgoing_call_ring | To trigger the Workflow rule when an outgoing call rings. |
| outgoing_call_start | To trigger the Workflow rule when an outgoing call starts. |
| outgoing_call_createedit | To trigger the Workflow rule when an outgoing call is created or edited. |
| outgoing_call_edit | To trigger the Workflow rule when an outgoing call is edited. |
| anyaction | To trigger the Workflow rule when any action happens on a call record. |
| delete | To trigger the Workflow rule when a call record is deleted. |
| missed_call | To trigger the Workflow rule when a missed call is logged or updated. |
For these types, specify the field criteria in the execute_when.details.criteria JSON object.
- criteriaJSON Object, mandatory
Field update condition details.
- repeatBoolean, mandatory
Specify whether the Workflow rule should be triggered multiple times for repeated every time the field is updated.
Possible values:
true - The Workflow rule will be triggered every time the specified field is updated.
false - The Workflow rule will be triggered only once. - match_allBoolean
Specifies whether all criteria must be met for the Workflow rule to trigger.
Possible values:
true - All field conditions must be satisfied for the rule to execute.
false - The rule will execute if any one of the conditions is met.
On section updates:
| Value | Description |
|---|---|
| incoming_call_field_update | To trigger the Workflow rule when a field in an incoming call section is updated. |
| scheduled_call_field_update | To trigger the Workflow rule when a field in a scheduled call section is updated. |
| outgoing_call_field_update | To trigger the Workflow rule when a field in an outgoing call section is updated. |
For these types, specify the section_ids and module details in the execute_when.details object. Refer to Section Updates for more details.
Sample Input for Calls module Trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Calls",
"id": "4876876000000033015"
}
},
"type": "incoming_call_createedit"
},
"module": {
"api_name": "Calls"
},
"name": "Testing Notes Trigger",
"description": "Testing",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"id": "4876876000011058044",
"type": "email_notifications"
}
]
},
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": {
"comparator": "less_than",
"field": {
"api_name": "Created_Time",
"id": "4876876000000002525"
},
"type": "value",
"value": "2022-04-01T01:00:00+05:30"
},
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
}
},
"criteria": {
"group_operator": "AND",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "CTI_Entry",
"id": "4876876000000033041"
},
"type": "value",
"value": true
},
{
"comparator": "greater_than",
"field": {
"api_name": "Call_Duration_in_seconds",
"id": "4876876000000033033"
},
"type": "value",
"value": "30"
}
]
}
},
}
]
}
]
}1.7 Appointments Module Triggers
Note:
Along with the special triggers as described below, you can also trigger Workflow rules based on any date or datetime fields in the Calls module.
You can configure Workflow rules to trigger on various record actions, overdue conditions, or when an appointment is marked complete.
Possible values for execute_when.type:
| Trigger Type | Description |
|---|---|
| Record Actions | |
| create | To trigger the Workflow rule when a new appointment is created. |
| reschedule | To trigger the Workflow rule when an appointment is rescheduled. |
| cancel | To trigger the Workflow rule when the appointment is canceled. |
| reassign | To trigger the Workflow rule when the appointment is reassigned to another user. |
| delete | To trigger the Workflow rule when the appointment is deleted. |
| marked_as_complete | To trigger the Workflow rule when the appointment is marked as complete. |
| anyaction | To trigger the Workflow rule when any of the above listed actions is performed on an Appointments record. |
| Overdue Trigger | |
| overdue | To trigger the Workflow rule when the appointment has crossed a time threshold after it was scheduled. |
For overdue, specify the time threshold details in the execute_when.details JSON object.
- fieldJSON Object, mandatory
The date or datetime field to monitor.
- periodstring, mandatory
The time unit.
Possible values: minutes, hours, days - unitinteger, mandatory
The number of time units after which the Workflow rule will be triggered.
Sample Input for Appointment module trigger
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"unit": 1,
"period": "hours"
},
"type": "overdue"
},
"module": {
"api_name": "Appointments__s"
},
"name": "Testing Emails Trigger",
"description": "Testing Emails Tigger",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"related_details": null,
"name": "Appointment Late",
"id": "4876876000011083014",
"type": "email_notifications"
}
]
},
"criteria_details": {
"relational_criteria": {
"module_selection": "all",
"criteria": null,
"module": null
},
"criteria": {
"comparator": "equal",
"field": {
"api_name": "Cancellation_Reason",
"id": "4876876000002362354"
},
"type": "value",
"value": "${EMPTY}"
}
}
}
]
}
]
}1.8 Facebook Triggers
You can configure to trigger the Workflow rule when user interactions happen on your Facebook pages.
Possible values for execute_when.type:
| Value | Description |
|---|---|
| fb_post_on_page | To trigger the Workflow rule when a new post is published on the Facebook page. |
| fb_comment_on_page | To trigger the Workflow rule when someone comments on a post on the Facebook page. |
| fb_like_on_post | To trigger the Workflow rule when someone likes a post on the Facebook page. |
| fb_send_message | To trigger the Workflow rule when someone sends a direct message. |
Sample Input for Facebook Triggers
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Facebook",
"id": "1702076000000725015"
}
},
"type": "fb_post_on_page"
},
"module": {
"api_name": "Facebook"
},
"name": "Testing Facbook Trigger",
"description": "Testing Facebook Tigger",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"related_details": null,
"id": "1702076000001443066",
"type": "email_notifications"
}
]
},
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": null,
"module": {
"api_name": "Leads",
"id": "1702076000000000125"
}
},
"criteria": {
"group_operator": "AND",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "PAGE",
"id": "1702076000000725018"
},
"type": "value",
"value": [
"One Piece",
"CRM testing"
]
},
{
"comparator": "contains",
"field": {
"api_name": "POST",
"id": "1702076000000725024"
},
"type": "value",
"value": "subscription"
}
]
}
}
}
]
}
]
}1.9 Twitter Triggers
You can configure to trigger the Workflow rule when user interactions happen on the twitter handle.
Possible values for execute_when.type:
| Value | Description |
|---|---|
| tw_mention_on | To trigger the Workflow rule when someone mentions a handle in a tweet. |
| tw_retweet_on_tweet | To trigger the Workflow rule when someone retweets a tweet by the handle. |
| tw_comment_on_tweet | To trigger the Workflow rule when someone replies to a tweet by the handle. |
| tw_send_message | To trigger the Workflow rule when someone sends a direct message to the handle. |
Sample Input
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Twitter",
"id": "1702076000000725042"
}
},
"type": "tw_send_message"
},
"module": {
"api_name": "Twitter",
"id": "1702076000000725042"
},
"name": "Testing Twitter DM Trigger",
"description": "Testing Tigger",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"related_details": null,
"id": "1702076000003965053",
"type": "email_notifications"
}
]
},
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": {
"comparator": "less_than",
"field": {
"api_name": "Created_Time",
"id": "1702076000000000481"
},
"type": "value",
"value": "2024-07-01T01:00:00+05:30"
},
"module": {
"api_name": "Contacts",
"id": "1702076000000000129"
}
},
"criteria": {
"group_operator": "OR",
"group": [
{
"comparator": "contains",
"field": {
"api_name": "HANDLE",
"id": "1702076000000725045"
},
"type": "value",
"value": [
"new_kview",
"Dracarys1408"
]
},
{
"comparator": "contains",
"field": {
"api_name": "MESSAGE",
"id": "1702076000000725057"
},
"type": "value",
"value": "subscription"
}
]
}
}
}
]
}
]
}2. Actions
Actions define the operations to be performed when the Workflow rule is triggered. You can configure Instant Actions, which execute immediately, and Scheduled Actions, which execute after a delay. Each action is specified in an actions array, inside the instant_actions or scheduled_actions object in workflow_rules.execute_when.conditions object.
Depending on how an action is configured, it can be one of the following:
Associative Actions: These actions must be created separately using their respective APIs. In the workflow rule configuration, you must associate them using their unique id. For example: field updates, email notifications, webhooks, etc.
Non-Associative Actions: These actions are defined entirely within the workflow rule input. You must provide all necessary configuration details in the input JSON. For example: create record, assign owner, schedule call, convert, etc.
Note: Associative or Non-Associative refers to how an action is defined and added, while Instant or Scheduled refers to when the action is executed.
This section lists the possible values for the type key in the action object and any additional keys specific to those action types. For a description of common JSON keys such as id, name, and related_details, refer to the Input JSON section at the beginning of this page.
2.1. Associative Actions
2.1.1 Field Update (actions.type : "field_updates")
This action updates a field in the record when the workflow rule is triggered. To associate a field update action, set the value of the type key to field_updates.
Note:
This type of action cannot be created as part of the workflow rule configuration. It must be created using the Create Field Update Actions API and then associate it here using its unique ID. Use the Get Field Update Actions API to retrieve the list of configured field update actions and their IDs.
Additional Keys in actions Object
- related_detailsJSON object, optional
Specify additional details relevant to the Field Update action.
- lookup_fieldJSON object, optional
Specify the unique ID and the field API name of the lookup field to be updated when the workflow executes. This is required when the field update involves updating a related record through a lookup relationship.
2.1.2 Email Notifications (actions.type: "email_notifications")
To send an email notification when the Workflow rule is triggered. To associate an email notification action, set the type key to "email_notifications".
Note:
Email notification actions must be preconfigured using the Create Email Notification Action API. You can then associate them to your workflow by referencing their ID. To fetch existing email notifications and their IDs, use the Get Email Notifications Actions API.
Additional Keys in actions Object
- related_detailsJSON object, optional
Specify additional details relevant to Email Notifications.
- best_timeBoolean, optional
Specify whether to send the email at the best time suggested by Zia.
Possible values:
true: Email will be scheduled for Zia’s recommended time.
false (default): Email will be sent immediately when the workflow executes.
Sample Input for associating Field Update and Email Notification actions
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads"
}
},
"type": "create"
},
"module": {
"api_name": "Leads"
},
"name": "Testing Actions",
"description": "Testing Email Notifications and Field Update actions",
"conditions": [
{
"sequence_number": 1,
"criteria_details": {
"criteria": {
"group_operator": "and",
"group": [
{
"group_operator": "and",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Annual_Revenue"
},
"value": "${NOTEMPTY}"
},
{
"comparator": "equal",
"field": {
"api_name": "Phone"
},
"value": "${NOTEMPTY}"
}
]
}
]
}
},
"instant_actions": {
"actions": [
{
"related_details": {
"lookup_field": {
"api_name": "Contact_Points",
"id": "4876876000010096044"
}
},
"id": "4876876000011017020",
"type": "field_updates"
},
{
"related_details": {
"best_time": true
},
"id": "4876876000010792012",
"type": "email_notifications"
}
]
}
}
]
}
]
}2.1.3 Tasks (actions.type: "tasks")
To assign a task when the Workflow rule is triggered. To associate a task action, set the type key to tasks.
Note:
Task actions must be configured in advance using the Create Automation Tasks API. You can then associate them to your workflow by specifying their unique ID. Use the Get Automation Tasks API to fetch the list of available task actions and their IDs.
2.1.4 Webhooks (actions.type: "webhooks")
This action invokes a webhook when the Worflow rule is triggered. To associate a webhook action, set the type key to webhooks.
Note:
Webhook actions must be created beforehand using the Create Webhook Action API. Once configured, you can link them to your workflow by referring to their unique ID. Use the Get Webhook Actions API to retrieve the list of available webhook actions and their IDs.
Sample Input for associating Webhooks and Tasks Actions
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads"
}
},
"type": "create"
},
"module": {
"api_name": "Leads"
},
"name": "Leads-Webhooks",
"description": "Testing Action",
"conditions": [
{
"sequence_number": 1,
"criteria_details": {
"criteria": {
"group_operator": "and",
"group": [
{
"group_operator": "and",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Annual_Revenue"
},
"value": "${NOTEMPTY}"
},
{
"comparator": "equal",
"field": {
"api_name": "Phone"
},
"value": "${NOTEMPTY}"
}
]
}
]
}
},
"instant_actions": {
"actions": [
{
"id":"4876876000000329768",
"type":"tasks"
},
{
"type": "webhooks",
"id":"4876876000007011001"
}
]
}
}
]
}
]
}2.1.5 Add Tags (actions.type: "add_tags")
To associate one or more tags to the record when the Workflow rule is triggered. Please note that you can only associate existing tags, and you cannot create new tags using this API. To associate a tag action, set the type key to add_tags.
Use the Create Tags API to create new tags in the module before referencing them in a workflow. Use the Get Tags API to fetch the list of available tags for a module, along with their IDs and names.
These are the other input keys in the actions.details JSON object, when the type key is add_tags:
- modulestring, optional
Specify the module where the tags are added.
- tagsJSON array, mandatory
An array of tag objects, each containing the ID or name of the tag.
- overwriteBoolean, mandatory
Indicates whether to replace existing tags with the new ones. If true, replaces existing tags with the new ones.
Sample Input for associating Tags
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads"
}
},
"type": "create"
},
"module": {
"api_name": "Leads"
},
"name": "Leads-Tasks",
"description": "Testing Action",
"conditions": [
{
"sequence_number": 1,
"criteria_details": {
"criteria": {
"group_operator": "and",
"group": [
{
"group_operator": "and",
"group": [
{
"comparator": "equal",
"field": {
"api_name": "Annual_Revenue"
},
"value": "${NOTEMPTY}"
},
{
"comparator": "equal",
"field": {
"api_name": "Phone"
},
"value": "${NOTEMPTY}"
}
]
}
]
}
},
"instant_actions": {
"actions": [
{
"type": "add_tags",
"module" : "Leads",
"details": {
"tags": [
{
"id" :"4876876000002526117"
},
{
"name" :"Active"
}
],
"overwrite": true
}
}
]
}
}
]
}
]
}2.1.6 Remove Tags (actions.type: "remove_tags")
To remove one or more tags from the record when the Workflow rule is triggered. To configure this action, set the value of the type key to remove_tags.
These are the other input keys in the actions.details JSON object, when the type key is remove_tags:
- tagsJSON array, mandatory
An array of tag objects, each containing the ID or name of the tag.
Sample Input for Remove Tags Action
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"criteria": {
"comparator": "less_than",
"field": {
"api_name": "Annual_Revenue",
"id": "4876876000000002617"
},
"type": "value",
"value": "10000000"
},
"repeat": true,
"match_all": false
},
"type": "field_update"
},
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"name": "Tags - remove - API",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"name": "P1",
"details": {
"tags": [
{
"name": "P1",
"id": "4876876000011037076"
}
]
},
"type": "remove_tags"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"relational_criteria": {
"module_selection": null,
"criteria": null,
"module": null
},
"criteria": null
}
}
]
}
]
}2.2. Non-Associative Actions
2.2.1 Create Record (actions.type: "create_record")
This action creates a record in the specified module when the workflow rule is triggered. To configure this action, set the value of the type key to create_record.
These are the other input keys in the actions.details JSON object, when the type key is create_record:
- moduleJSON object, mandatory
Specify the target module in which the record will be created. Specify the unique ID and the API name of the module.
- layoutJSON object, mandatory
Specify the details of the layout in which the record should be created. The details include the unique ID and the API name of the Layout.
- field_mappingsJSON array, mandatory
Specify the list of fields and values to be set in the new record.
- fieldJSON object, mandatory
Represents the target field in the new record. Specify the field API name and the unique ID of the field.
- typestring, mandatory
Specify how the field value is sourced when creating the record.
Possible values:
static : A fixed value that is directly assigned to the target field. Use this for constant values like strings, numbers, or static objects (e.g., owner).
merge_field: A dynamic value fetched from the source record that triggered the Workflow rule. Use merge field syntax like ${!Leads.Last_Name} or ${!Notes.Note_Content}. - valuestring, mandatory
The actual value to insert into the field. The format depends on the type.
If the value of type is static, this is a direct value (string, number, or object).
If the value of type is merge_field, this is a merge field expression (e.g., ${!Leads.Last_Name} or ${!Notes.Note_Content}).
Sample Input JSON for associating a Create Record action
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Notes",
"id": "4876876000000002197"
}
},
"type": "create"
},
"module": {
"api_name": "Leads"
},
"layout": {
"name": "Standard",
"id": "4876876000000091033"
},
"name": "Testing Create record action",
"description": "Testing action",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"type": "create_record",
"details": {
"module": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"layout": {
"name": "Standard",
"id": "4876876000000091033"
},
"field_mappings": [
{
"field": {
"api_name": "Owner",
"id": "4876876000000002485"
},
"type": "static",
"value": {
"name": "${CURRENTUSER}"
}
},
{
"field": {
"api_name": "Last_Name",
"id": "4876876000000002491"
},
"type": "merge_field",
"value": "${!Leads.Last_Name}"
},
{
"field": {
"api_name": "Description",
"id": "4876876000000002553"
},
"type": "merge_field",
"value": "${!Notes.Note_Content}"
},
{
"field": {
"api_name": "Department",
"id": "4876876000000002501"
},
"type": "static",
"value": "Test"
}
]
}
}
]
},
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": null,
"module": {
"api_name": "Notes",
"id": "4876876000000002197"
}
},
"criteria": null
}
}
]
}
]
}2.2.2 Schedule a Call(actions.type: "schedule_call")
To schedule a call automatically when the Workflow rule is triggered. To configure this action, set the value of the type key to create_record.
These are the other input keys in the actions.details JSON object, when the type key is schedule_call:
- moduleJSON object, mandatory
Specify the module in which the call will be created. In this case, this is the Calls module. Specify the unique ID and api_name.
- layoutJSON object, mandatory
Specify the details of the layout in which the call record should be created. The details include the unique ID and the API name of the Layout.
- field_mappingsJSON array, mandatory
Specify the list of fields and values to be set in the new record.
- fieldJSON object, mandatory
Represents the target field in the new call record. Specify the field API name and the unique ID of the field.
- typestring, mandatory
Specify how the field value is sourced when creating the record. The table lists the possible values of type key:
Type Description static A fixed value that is directly assigned to the target field. Use this for constant values like strings, numbers, or static objects (e.g., owner). merge_field A dynamic value fetched from the source record that triggered the Workflow rule. For instance, to set the call subject to the Lead Owner's name, use type as merge_field and value as ${!Leads.Owner}. execution_time Use this for date or datetime fields to set a time relative to when the workflow is triggered. - valuestring or JSON object, mandatory
The actual value to insert into the field. The format depends on the type.
If type is Value Format static A direct value like a string, number, or an object. merge_field A merge field expression (e.g., ${!Leads.Last_Name} or ${!Notes.Note_Content}). execution_time A JSON object with keys unit, period, sign, time, and trigger_field.
Sample input for Schedule Call action
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
}
},
"type": "create"
},
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"description": null,
"source": "crm",
"name": "Schedule Call action - Testing",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"name": "Calls",
"details": {
"layout": {
"name": "Standard",
"id": "4876876000000091005"
},
"field_mappings": [
{
"display_value": "Outbound",
"field": {
"api_name": "Call_Type",
"id": "4876876000000033021"
},
"type": "static",
"value": "Outbound"
},
{
"display_value": "Scheduled",
"field": {
"api_name": "Outgoing_Call_Status",
"id": "4876876000000215003"
},
"type": "static",
"value": "Scheduled"
},
{
"display_value": "Created Time plus 2 business day(s) 10:30 AM",
"field": {
"api_name": "Call_Start_Time",
"id": "4876876000000033029"
},
"type": "execution_time",
"value": {
"unit": "2",
"period": "business_days",
"trigger_field": "${!Leads.Created_Time}",
"sign": "plus",
"time": "10:30"
}
},
{
"display_value": "${Leads.Lead Owner}",
"field": {
"api_name": "Owner",
"id": "4876876000000033017"
},
"type": "merge_field",
"value": "${!Leads.Owner}"
},
{
"display_value": "Prospecting",
"field": {
"api_name": "Call_Purpose",
"id": "4876876000000033023"
},
"type": "static",
"value": "Prospecting"
},
{
"display_value": "Prospecting",
"field": {
"api_name": "Call_Agenda",
"id": "4876876000000768818"
},
"type": "static",
"value": "Prospecting"
},
{
"display_value": "Prospecting - 1",
"field": {
"api_name": "Subject",
"id": "4876876000000033019"
},
"type": "static",
"value": "Prospecting - 1"
}
],
"module": {
"api_name": "Calls",
"id": "4876876000000033015"
}
},
"type": "schedule_call"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"relational_criteria": {
"module_selection": null,
"criteria": null,
"module": null
},
"criteria": null
}
}
]
}
]
}2.2.3 Add Meeting (actions.type: "add_meeting")
This action schedules a meeting in the Events module when the Workflow rule is triggered. To configure an Add Meeting action, set the value of the type key to add_meeting and provide the necessary configuration under the details object.
These are the other input keys in the actions.details JSON object, when the type key is add_meeting:
- moduleJSON object, mandatory
Specify the module in which the meeting should be created. In this case, this is the Events module. Include the ID and api_name.
- layoutJSON object, mandatory
Specify the details of the layout in which the meeting record should be created. The details include the unique ID and the api_name of the layout.
- field_mappingsJSON array, mandatory
List of fields and values to be set in the meeting record.
- fieldJSON object, mandatory
Represents the target field in the new meeting record. Specify the field API name and the unique ID of the field.
- typestring, mandatory
Specify how the field value is sourced when creating the record.
Type Description static A fixed value that is directly assigned to the target field. Use this for constant values like strings, numbers, or static objects (e.g., owner). merge_field A dynamic value fetched from the source record that triggered the Workflow rule. Use merge field syntax like ${!Leads.Last_Name} or ${!Notes.Note_Content}. execution_time Used for date or datetime fields to specify a time relative to when the workflow is triggered. Requires a JSON object with keys such as unit, period, sign, time, and trigger_field. composite Used for multi-value fields like Participants. The value should be an array of JSON objects, each with type and either api_name or id. - valuestring or JSON object, mandatory
The actual value to insert into the field. The format depends on the type:
Type Description static Provide a direct value (string, number, or object). merge_field Use a merge field expression (e.g., ${!Leads.Last_Name}). execution_time Provide a JSON object with unit, period, sign, time, and trigger_field. composite The value should be an array of participants, where each item is a JSON object with either a field reference or user ID.
- meeting_durationJSON object, mandatory
Denotes the duration of the meeting. Specify the time period and unit.
- invite_participantsBoolean, optional
Specify whether to send invites to the participants. Default value is false.
- host_unavailableJSON object, optional
Specify fallback option in case the host is not available. If the host_unavailable key is specified, either assign_record_owner_as_host or assign_task must be specified.
- assign_record_owner_as_hostBoolean, mandatory if the host_unavailable object is used and assign_task is not specified
Specify whether to assign the record owner as host if the specified host is unavailable.
- assign_taskJSON object, mandatory if the host_unavailable object is used and assign_record_owner_as_host is not specified.
Specify the task to be assigned if the host is unavailable. Specify the unique ID and the name of the task.
Sample Input for Add Meeting action
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
}
},
"type": "create"
},
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"name": "Add meeting",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"name": "Meeting Action ",
"details": {
"layout": {
"name": "Standard",
"id": "4876876000000091057"
},
"field_mappings": [
{
"field": {
"api_name": "Event_Title",
"id": "4876876000000002295"
},
"type": "static",
"value": "Welcome meeting"
},
{
"field": {
"api_name": "Start_DateTime",
"id": "4876876000000096001"
},
"type": "execution_time",
"value": {
"unit": "1",
"period": "business_days",
"trigger_field": "${!Leads.Created_Time}",
"sign": "plus",
"time": "11:00"
}
},
{
"field": {
"api_name": "All_day",
"id": "4876876000000070003"
},
"type": "static",
"value": "false"
},
{
"field": {
"api_name": "End_DateTime",
"id": "4876876000000096003"
},
"type": "execution_time",
"value": {
"unit": "1",
"period": "business_days",
"trigger_field": "${!Leads.Created_Time}",
"sign": "plus",
"time": "11:10"
}
},
{
"field": {
"api_name": "Owner",
"id": "4876876000000002293"
},
"type": "merge_field",
"value": "${!Leads.User_1}"
},
{
"field": {
"api_name": "Participants",
"id": "4876876000000070005"
},
"type": "composite",
"value": [
{
"api_name": "${!CURRENTRECORD}",
"type": "field"
},
{
"api_name": "${!Leads.Referred_By}",
"type": "field"
},
{
"api_name": "${!Leads.Contact}",
"type": "field"
}
]
}
],
"module": {
"api_name": "Events",
"id": "4876876000000002195"
},
"meeting_duration": {
"unit": 10,
"period": "minutes"
},
"invite_participants": true,
"host_unavailable": {
"assign_record_owner_as_host": true
}
},
"type": "add_meeting"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"relational_criteria": {
"module_selection": null,
"criteria": null,
"module": null
},
"criteria": null
}
}
],
"status": {
"active": true
}
}
]
}2.2.4 Convert Records (actions.type: "convert")
Use this action to automatically convert Leads, Quotes, or Sales Orders when a record meets the workflow criteria. To configure this action, set the value of the type key to convert.
Note:
This action must be defined directly within the workflow rule. It cannot be created separately and associated using an ID.
These are the other input keys in the actions.details JSON object, when the type key is convert:
- create_dealBoolean, mandatory for Lead module
Specify whether to create a Deal during Lead conversion or not.
- carry_tagsJSON array, optional
Specify the module (Contacts, Accounts, Deals, Invoices, etc.) to which tags from the source record should be carried when the record is converted. Each item in the array must include the id and api_name of the target module.
- move_attachment_toJSON object, optional
Specify the module to which attachments from the source record should be moved. Provide the api_name and ID of the module.
- change_ownerJSON object, optional
Configure ownership behavior during conversion. Set change_owner.apply_assignment_threshold key as true to apply assignment threshold.
- add_to_existing_contactBoolean, optional
Specify whether to link the record to an existing Contact, instead of creating a new one.
- add_to_existing_accountBoolean, optional
Specify whether to link the record to an existing Account, instead of creating a new one.
- contact_rolestring, optional
Specify the unique ID of the Contact Role to be assigned if a deal is created.
- convert_toJSON object, optional
Used when converting modules like Quotes. Specify the target module using id and api_name
- field_mappingsJSON array, optional
Specify the fields and values to set in the new record in the target module.
- fieldJSON object, mandatory
Represents the target field in the new meeting record. Specify the field API name and the unique ID of the field.
- typestring, mandatory
Specify how the field value is sourced when creating the record.
Type Description static A fixed value that is directly assigned to the target field. Use this for constant values like strings, numbers, or static objects (e.g., owner). merge_field A dynamic value fetched from the source record that triggered the Workflow rule. Use merge field syntax like ${!Leads.Last_Name} or ${!Notes.Note_Content}. execution_time Used for date or datetime fields to specify a time relative to when the workflow is triggered. Requires a JSON object with keys such as unit, period, sign, time, and trigger_field. composite Used for multi-value fields like Participants. The value should be an array of JSON objects, each with type and either api_name or id. - valuestring or JSON object, mandatory
The actual value to insert into the field. The format depends on the type:
Type Description static Provide a direct value (string, number, or object). merge_field Use a merge field expression (e.g., ${!Leads.Last_Name}). execution_time Provide a JSON object with unit, period, sign, time, and trigger_field. composite The value should be an array of participants, where each item is a JSON object with either a field reference or user ID.
Sample Input for 'Convert' action
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"repeat": false
},
"type": "edit"
},
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"description": "Test - Convert Action",
"name": "Test - Convert Action - API",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"details": {
"field_mappings": [
{
"field": {
"api_name": "Amount",
"id": "4876876000000002557"
},
"type": "static",
"value": "120000000"
},
{
"field": {
"api_name": "Deal_Name",
"id": "4876876000000002559"
},
"type": "static",
"value": "D1092"
},
{
"field": {
"api_name": "Closing_Date",
"id": "4876876000000002561"
},
"type": "execution_time",
"value": {
"period": "business_days",
"unit": "2",
"trigger_field": "${!Leads.Date_Time_2}",
"sign": "plus"
}
},
{
"field": {
"api_name": "Stage",
"id": "4876876000000002565"
},
"type": "static",
"value": "Closed Won"
},
{
"field": {
"api_name": "Campaign_Source",
"id": "4876876000000002575"
},
"type": "static",
"value": {
"name": "Q1 Marketing Blitz",
"id": "4876876000010193001"
}
},
{
"field": {
"api_name": "Currency",
"id": "4876876000000050013"
},
"type": "merge_field",
"value": "${!Leads.Currency}"
},
{
"field": {
"api_name": "Pipeline",
"id": "4876876000000193001"
},
"type": "static",
"value": "Standard (Standard)"
}
],
"change_owner": {
"apply_assignment_threshold": true
},
"carry_tags": [
{
"api_name": "Contacts",
"id": "4876876000000002179"
}
],
"create_deal": true,
"move_attachment_to": {
"api_name": "Contacts",
"id": "4876876000000002179"
},
"add_to_existing_account": false,
"add_to_existing_contact": true,
"contact_role": "4876876000001283052"
},
"type": "convert"
}
]
},
"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": "10000000000"
}
}
}
]
}
]
}2.2.5 Social Actions
Social actions let you automatically engage with your audience on social media when the Workflow rule is triggered. To configure a social action, set the value of the type key to one of the following:
| type | Description |
|---|---|
| comment_to_post | To add a comment on a Facebook post. |
| reply_to_comment | To post a reply to a Facebook comment. |
| like_to_comment | To like a Facebook comment. |
| reply_to_message | To send a reply to a Facebook private message. |
These actions are available only when the trigger module is a supported social module (like Facebook), and the workflow type is fb_post_on_page, fb_comment_on_page, or fb_send_message.
These are the other input keys in the actions.details JSON object:
- contentstring, mandatory
The message content to be posted or replied with. This is required for comment_to_post, reply_to_comment, and reply_to_message. Not applicable for like_to_comment.
Sample Input for Social media actions
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Facebook",
"id": "1702076000000725015"
}
},
"type": "fb_comment_on_page"
},
"module": {
"api_name": "Facebook",
"id": "1702076000000725015"
},
"name": "Social Actions - Test API",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"details": {
"content": "Hi, thank you for contacting us. Please check DM for more details."
},
"type": "reply_to_comment"
},
{
"type": "like_to_comment"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"relational_criteria": {
"module_selection": "specific",
"criteria": null,
"module": {
"api_name": "Leads",
"id": "1702076000000000125"
}
},
"criteria": null
}
}
]
}
]
}2.2.6 Create Record on Email Received (actions.type: "create_record_email")
This action creates a record in the specified module (such as Leads or Contacts) when the workflow is triggered by an incoming email. To configure this action, set the value of the type key to create_record_email.
Note:
- This action is only applicable when the trigger module is Emails.
For this action, the relational_criteria object inside criteria_details must be configured as:
- module_selection: "unknown"
- criteria: null
- module: null
This is because the action is performed in response to an email activity, and not on a record from a related module.
These are the other input keys in the actions.details JSON object, when the type key is convert:
- moduleJSON object, mandatory
Specify the module in which the new record will be created (e.g., Leads or Contacts). Provide the module's ID and api_name.
- field_mappingsJSON array, mandatory
Defines how the fields in the new record should be populated. Only the Owner field is supported for this action. Each object must include:
- fieldJSON object, mandatory
Specify the API name and ID of the target field. For this action, specify the details of the Owner field.
- typestring, mandatory
Specify the type of value to insert. Possible value: static
- valuestring, mandatory
The actual value to insert into the field. For the owner field, you can specify a user, a role, or a group.
Sample Input for create_record_email action
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Emails",
"id": "4876876000000014163"
}
},
"type": "email_received"
},
"module": {
"api_name": "Emails",
"id": "4876876000000014163"
},
"name": "Create Email Record",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"details": {
"field_mappings": [
{
"field": {
"api_name": "Owner",
"id": "4876876000000002589"
},
"type": "static",
"value": {
"type": "users",
"users": [
{
"name": "Patricia Boyle",
"id": "4876876000000327001"
}
]
}
}
],
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"type": "create_record_email"
},
"type": "create_record_email"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"relational_criteria": {
"module_selection": "unknown",
"criteria": null,
"module": null
},
"criteria": {
"comparator": "equal",
"field": {
"api_name": "Has_Attachment",
"id": "4876876000000203007"
},
"type": "value",
"value": "true"
}
}
}
]
}
]
}2.2.7 Assign Owner (actions.type: "assign_owner")
Use this action to automatically assign ownership of the record and its related records when the workflow rule is triggered. You can assign the record to a specific user, role, group, user field, or dynamically based on criteria or assignment rules. To configure this action, set the value of the type key to assign_owner.
These are the other input keys in the actions.details JSON object, when the type key is assign_owner:
- moduleJSON object, mandatory
Specify the module in which the ownership assignment is to be applied. Provide the module's ID and api_name.
- assign_toJSON array, mandatory
Specifies how the new owner should be assigned.
- typestring, mandatory
Specify the method used to assign ownership.
Possible values:
- user – Assign the record a specific user. You can add multiple users, and ownership will be assigned to them in a round-robin pattern. For each user, include an object in the assign_to array with "type": "user" and a resource object containing the user's ID and name.
- role – Assign to users under a specified role. Add an object in the assign_to array with "type": "role" and a resource object that includes the role’s ID and name.
- group – Assign to users in a specified user group. Add an object in the assign_to array with "type": "group" and a resource object that includes the group's ID and name. If the group contains multiple users, the records will be assigned to them in a round-robin pattern.
- merge_field – Assign the record to a user specified in a user-type field within the record. Add an object in the assign_to array with "type": "merge_field". In this case, use the details object to provide the api_name of the user field using merge field syntax (e.g., "${!Leads.Contact_User}").
- criteria – Assign to users who meet a specific condition. Add an object in the assign_to array with "type": "criteria". In this case, use the details object to define a criteria block with field conditions. You can use comparator, field (with api_name and ID), type, and value keys to construct conditions. You can also group multiple conditions using group_operator (e.g., "AND" or "OR") and a group array. If multiple users satisfy the criteria, ownership will be rotated among them in a round-robin pattern.
- assignment_rule – Assign based on an existing assignment rule. In this case, add an object in the assign_to array with "type": "assignment_rule". Use the resource object to specify the assignment rule’s ID and name. This type only supports associating existing assignment rules. You cannot create a new assignment rule here.
- related_recordsJSON array, optional
Specify the list of related modules (Tasks, Calls and Events) whose ownership should also be updated.
- notifyBoolean, optional
Specify whether or not to send email notifications to the new owner.
- apply_assignment_thresholdBoolean, optional
Specify whether to apply assignment thresholds defined in the system.
- user_availability_based_onJSON array, optional
Use this to assign records only to users who are currently online via the web interface. This key is applicable only when assigning owners based on user category or user criteria. If none of the eligible users are online at the time of assignment, the action will be skipped and no owner will be assigned.
Supported values: online_status, null
Additional Keys in actions Object
- related_detailsJSON object, optional
Specify additional details relevant to the Assign Owner action.
- lookup_fieldJSON object, optional
Specify the unique ID and the API name of the lookup field. When specified, the owner of the related record in this lookup field will be assigned when the workflow executes.
Sample input for Assign Owner action
Copied{
"workflow_rules": [
{
"execute_when": {
"details": {
"trigger_module": {
"api_name": "Leads",
"id": "4876876000000002175"
}
},
"type": "create"
},
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"name": "Assign Owner - Test",
"conditions": [
{
"sequence_number": 1,
"instant_actions": {
"actions": [
{
"related_details": {
"lookup_field": {
"api_name": "Lookup_2",
"id": "4876876000007874092"
}
},
"details": {
"apply_assignment_threshold": true,
"assign_to": [
{
"resource": {
"name": "Rule 01",
"id": "4876876000009677003"
},
"type": "assignment_rule"
}
],
"module": {
"api_name": "Leads",
"id": "4876876000000002175"
},
"related_records": [
{
"api_name": "Tasks",
"id": "4876876000000002193"
},
{
"api_name": "Events",
"id": "4876876000000002195"
},
{
"api_name": "Calls",
"id": "4876876000000033015"
}
],
"user_availability_based_on": null,
"notify": false
},
"type": "assign_owner"
}
]
},
"scheduled_actions": null,
"criteria_details": {
"criteria": {
"comparator": "greater_than",
"field": {
"api_name": "Annual_Revenue",
"id": "4876876000000002617"
},
"type": "value",
"value": "10000000"
}
}
}
]
}
]
}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"
}
]
}