Create Assignment Rule

Purpose

To create an Assignment Rule for your organization.

Endpoints

POST /settings/automation/assignment_rules

Request Details

Request URL

{api-domain}/crm/{version}/settings/automation/assignment_rules

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Supported modules

Leads, Accounts, Contacts, Deals, Tasks, Cases, custom modules, and team modules

Scope

ZohoCRM.settings.assignment_rules.CREATE

Parameters

modulestring, mandatory
Specify the module for which you want to create an assignment rule. Refer to the Get Modules Metadata API to retrieve the module API names.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/assignment_rules?module=Leads"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@createRule.json"

Input JSON

The assignment_rules JSON array is the root key that contains the details to create an Assignment Rule in your organization. The array can contain only one object.

namestring, mandatory
Specify the name of the Assignment Rule. The name must be unique within the module.
descriptionstring, optional
Specify the purpose of the assignment rule.
default_assigneeJSON object, mandatory
Specify the default assignee to whom the record is assigned when no rule entry criteria match or when the eligible users are unavailable.
- typestring, mandatory
  Specify the type of assignee.
  Possible values: user
- resourceJSON object, mandatory
  Specify the default assignee. The resource object supports the following keys:
  - api_name, string: Specify ${CURRENTUSER} to assign the record to the logged-in user.
  - id, string: Specify the unique ID of the user.
  Note: Provide either id or api_name for the resource key.

rule_entriesJSON array, mandatory

Specify the list of rule entries that determine how records are assigned. Rule entries are evaluated in the order in which they appear in the rule_entries array. When a record matches a rule entry, the record is assigned according to that entry and the remaining entries are not evaluated. If the record does not match any rule entry, it is assigned to the default_assignee.

criteriaJSON object, mandatory
Specify the conditions that a record must meet for the rule entry to be applied. The conditions are based on the values of fields in the module.
- group_operatorstring, mandatory for more than one condition
  Specify the logical operator used to evaluate multiple conditions.
  Possible values: OR, AND
- groupJSON array, mandatory for more than one condition
  Specify the list of conditions to be evaluated. Each condition contains a field, comparator, and value.
  - fieldJSON object, mandatory
    Specify the field to be evaluated.
    - api_namestring, mandatory
      Specify the API name of the field. Use the Get Fields Metadata API to fetch field API names.
    - idstring, mandatory
      Specify the unique ID of the field.
  - comparatorstring, mandatory
    Specify the comparison operator used to evaluate the field value.
    The supported comparators vary based on the field data type, such as Single Line, Multi-line, Picklist, and Auto-number. Refer to the Setting Assignment Rules documentation to learn which field types can and cannot be compared in criteria.
  - valuestring, mandatory
    Specify the value to compare with the field value.

assign_toJSON object, mandatory

Specify how the record should be assigned when the rule entry criteria matches.

Note: Zoho CRM first evaluates rule_entries.criteria to check whether the record matches the rule entry. If it matches, assign_to determines the assignee. When assign_to.type is criteria, then the assign_to.criteria determines which user receives the matching records. You can specify multiple users. Matching records are assigned to the users in a round-robin manner. For the role type, you can specify only one role, and matching records are assigned to users in that role in a round-robin manner.

resourcesJSON array, mandatory
Specify the users, roles, or groups to whom the record can be assigned when the assignment condition is satisfied.
- idstring, mandatory
  Specify the unique ID of the user, role, or group.
criteriaJSON object, mandatory
Specify the condition used to determine which user should be assigned the records that match the rule entry criteria. This key is applicable only when assign_to.type is set to criteria. For other assign_to.type values, specify the assignee using the resources key.
- comparatorstring, mandatory
  Specify the comparison operator used to determine which user should be assigned the criteria-matching records.
  Possible values: equal, contains
- fieldJSON object, mandatory
  Set the condition by specifying the fields in the Users module to determine who should receive the criteria-matching records. Use the Get Fields Metadata API to fetch field API names from the Users module.
  - api_namestring, mandatory
    Specify the API name of the Users module field.
  - idstring, mandatory
    Specify the unique ID of the Users module field.
- typestring, mandatory
  Specify the type of comparison used in the assignment condition.
  Possible values: value
- valuestring, mandatory
  Specify the value used to evaluate the assignment condition.

typestring, mandatory

Specify the category to which the record should be assigned when the criteria matches.

Possible values:

assign_to.type	Description	Dependent field	Module Support
criteria	Dynamically assigns records based on field-level conditions.	assign_to.criteria	All supported modules
users	Assigns records to one or more specific users.	assign_to.resources	All supported modules
role	Assigns records to users in a specific role.	assign_to.resource	Org modules only
group	Assigns records to users in a group.	assign_to.resource	Org modules only
profile	Assigns records to users under a specific profile.	assign_to.resource	Private modules only
zia_suggested_users	Uses Zia (AI) to determine the best owner.	None	Org modules only

Note

assign_to:
- The required fields in assign_to depend on the value of type.
  - For type = users, specify one or more users in the resources array.
  - For type = role, group, or profile, specify the assignee using the resource object.
  - For type = criteria, specify the assignment condition using the criteria object.
  - For type = zia_suggested_users, no dependent field is required.
rule_entries:
- Each Assignment Rule can contain multiple rule_entries.
- The maximum number of rule entries allowed in an Assignment Rule depends on the Zoho CRM edition.

Edition	Maximum Rule Entries per Assignment Rule
Standard	10
Professional	25
Enterprise	100
CRM Plus	100
Zoho One	100
Ultimate	100
Developer	5

followup_actionsJSON array, optional
Specify the actions to be executed after a record is successfully assigned through a rule entry.
Currently, task creation is supported as a follow-up action.
- typestring, mandatory
  Specify the type of follow-up action.
  Possible values: tasks
- resourcesJSON array, mandatory
  Specify the list of tasks to be created for the assigned record owner.
  - idstring, mandatory
    Specify the unique ID of the task template to be used as a follow-up action. Use the Automation Tasks to retrieve the Task ID.
    Note: You can specify only one task as a follow-up action for each rule entry.
user_availability_based_onJSON array, optional
User availability is checked based on:
- Online status (logged in to Zoho CRM)
- Shift timing (configured working hours in Zoho CRM)
If this key is not specified, user availability is not checked before assigning the record.
Possible values:
- online_status: Assigns records only to users who are currently online.
- shift_timing: Assigns records only to users who are within their configured working hours.
Note:
- You can specify more than one condition. All conditions must be satisfied for the user to be eligible.
- If none of the eligible users are available based on the specified conditions, the record is assigned to the default_assignee.

Note

You can create only one Assignment Rule per API call.
Rule entries are evaluated in the order in which they appear in the rule_entries array.
If a record does not match any rule entry, it is assigned to the default_assignee.
If user_availability_based_on is not specified, the record is assigned to the default assignee.
If user availability is not specified, user availability is not checked before assignment.
When multiple users are eligible for assignment, records are assigned in a round-robin manner.

Sample Input with type "criteria"

Copied{
    "assignment_rules": [
        {
            "default_assignee": {
                "type": "user",
                "resource": {
                    "api_name": "${CURRENTUSER}"
                }
            },
            "rule_entries": [
                {
                    "criteria": {
                        "field": {
                            "api_name": "Email"
                        },
                        "comparator": "contains",
                        "value": "zohocrm@mail.com"
                    },
                    "assign_to": {
                        "resources": [
                            {
                                "name": "Kane",
                                "id": "2276164000000799020"
                            }
                        ],
                        "criteria": {
                            "comparator": "equal",
                            "field": {
                                "api_name": "city",
                                "id": "2276164000000000205"
                            },
                            "type": "value",
                            "value": "Chennai"
                        },
                        "type": "criteria"
                    },
                    "user_availability_based_on": [
                        "online_status"
                    ], 
                    "followup_actions": [
                        {
                            "resources": [
                                {
                                    "name": "Follow up - ${Leads.Last Name} for ${Leads.Company}",
                                    "id": "5725767000000416363"
                                }
                            ],
                            "type": "tasks"
                        }
                    ]

                }
            ],
            "name": "Rule with Followup task",
            "description": "Assigning all Lead records"
        }
    ]
}

Sample Input with type "Zia"

Copied{
    "assignment_rules": [
        {
            "default_assignee": {
                "type": "user",
                "resource": {
                    "api_name": "${CURRENTUSER}"
                }
            },
            "module": {
                "api_name": "Leads",
                "id": "2276164000000000125"
            },
            "name": "Lead Rule with type profile",
            "description": "Assigning all Lead records",
            "rule_entries": [
                {
                    "criteria": {
                        "field": {
                            "api_name": "Email"
                        },
                        "comparator": "contains",
                        "value": "zohocrm@mail.com"
                    },
                    "assign_to": {
                        "type": "zia_suggested_users" //supported_only_for_org_module
                    },
                    "user_availability_based_on": [
                        "online_status"
                    ]
                }
            ]
        }
    ]
}

Sample Input with type "group"

Copied{
    "assignment_rules": [
        {
            "default_assignee": {
                "type": "user",
                "resource": {
                    "api_name": "${CURRENTUSER}"
                }
            },
            "module": {
                "api_name": "Leads",
                "id": "2276164000000000125"
            },
            "name": "Lead Rule with type group",
            "description": "Assigning all Lead records",
            "rule_entries": [
                {
                    "criteria": {
                        "field": {
                            "api_name": "Email"
                        },
                        "comparator": "contains",
                        "value": "zohocrm@mail.com"
                    },
                    "assign_to": {
                        "type": "group",
                        "resource": {
                            "id": "2276164000001042090"
                        }
                    },
                    "user_availability_based_on": [
                        "online_status"
                    ]
                }
            ]
        }
    ]
}

Possible Errors

INVALID_DATAHTTP 400
Invalid data
Resolutions:
- You can create only one assignment rule per API call. Make sure the assignment_rules array contains only one object.
- The ID specified in followup_actions key [assignment_rules.rule_entries.followup_actions.resources.id] is invalid. Specify a valid Automation Task ID.
- An invalid value is specified in type key [assignment_rules.rule_entries.assign_to.type]. Specify a supported value. Refer to the type table in the Input JSON section.
- The ID provided in assign_to key [assignment_rules.rule_entries.assign_to.resources.id] is invalid. Specify a valid user, role, or group ID. Refer to the Input JSON section for details.
INVALID_MODULEHTTP 400
Invalid module
Resolution: The specified module is invalid. Use the Get Modules Metadata API to retrieve the valid module API name.
NOT_SUPPORTEDHTTP 400
Unsupported module
Resolution: The specified module does not support assignment rules. Refer to the Supported modules section and pass only the supported module.
DUPLICATE_DATAHTTP 400
Duplicate data provided
Resolution: The name of the assignment rule already exists. Specify a unique name.
REQUIRED_PARAM_MISSINGHTTP 400
Required parameter is missing
Resolution: The module parameter is required to create an assignment rule. Specify a valid module in the request. Refer to the Parameters section.
DEPENDENT_MISMATCHHTTP 400
Dependent mismatch occurred
Resolution: The value "type": "profile" is supported only for private modules. Do not use profile type for org modules.
NO_PERMISSIONHTTP 400
No permission to create the assignment rule
Resolution: You do not have permission to create assignment rules. Contact your administrator to enable the required permissions.
LIMIT_EXCEEDEDHTTP 400
Limit exceeded to create an assignment rule
Resolution: You have reached the maximum limit for creating Assignment Rules in your edition. Refer to feature-wise comparison of Zoho CRM Editions to check the Assignment Rule limits for your edition.
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 Endpoints section for details.
OAUTH_SCOPE_MISMATCHHTTP 401
Unauthorized
Resolution: The client does not have a valid scope to create the assignment rule. Create a new token with valid scope. Refer to the Scope section for details.
AUTHENTICATION_FAILUREHTTP 401
Authentication failed
Resolution: Pass the access token in the request header of the API call.
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 details.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in the server. Contact support team.

Sample Response

Copied{
    "assignment_rules": [
        {
            "code": "SUCCESS",
            "details": {
                "rule_entries": [
                    {
                        "id": "2276164000003551075"
                    }
                ],
                "id": "2276164000003551073"
            },
            "message": "Assignment rule CREATED successfully",
            "status": "success"
        }
    ]
}