Create Assignment Rule

Purpose

To create assignment rules 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

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"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@createRule.json"

Input JSON

assignment_rulesJSON array, mandatory

Specify the list of assignment rules to be created.

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 owner when a record is created using the assignment rule.
- typestring, mandatory
  Specify the type of assignee.
  Possible values: user
- resourcestring, mandatory
  Specify the user to whom the record is assigned by default.
  Possible value:
  - 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 object, mandatory

Define how record ownership should be assigned in Zoho CRM. Each rule contains a list of entries. These entries are validated one by one, in order.
When a record matches the first condition, the system:

Assigns the record to the specified user, role, or criteria
Stops checking the remaining entries.

assign_toJSON object, mandatory

Specify who the record is assigned to when the rule entry matches.

criteriaJSON object, mandatory
Specify the condition that determines when the rule entry is applied. The system assigns records based on attributes such as location, email, industry, or custom fields.
- group_operatorstring, mandatory
  Specify the logical operator used to evaluate the conditions.
  Possible values: "OR" and "AND"
- groupJSON array, mandatory
  Specify the list of conditions evaluated for the rule entry.
  - fieldJSON object, mandatory
    Specify the field API name to be evaluated. Use the Get Fields Metadata API to fetch field API names.
  - comparatorstring, mandatory
    Specify the operator used to compare 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.

typeJSON object, mandatory

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

Possible values:

value for the "type" key ("type": {{value}})	Description	Required Fields	Module Support
criteria	Dynamically assigns records based on field-level conditions	criteria	All supported modules
users	Assigns records to one or more specific users	resources	All supported modules
role	Assigns records to users belonging to a specific role	resource.id	Org modules only
group	Assigns records to a group	resource.id or resources	Org modules only
profile	Assigns records to users under a specific profile	resource.id	Private modules only
zia_suggested_users	Uses Zia (AI) to determine the best owner	None	Org modules only

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 rule entry's ID.
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)
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.

Note

You can create only one assignment rule per API call.
If rule_entries are not defined, all records are assigned to the default assignee.
default_assignee:
- The default assignee is applied only if no rule entry criteria match.
- Setting a default assignee is strongly recommended to prevent unassigned records.
- The default assignee must be an active user in the organization

Sample Input with type "criteria"

Copied{
    "assignment_rules": [
        {
            "default_assignee": {
                "type": "user",
                "resource": {
                    "api_name": "${CURRENTUSER}"
                }
            },
            "rule_entries": [
                {
                    "assign_to": {
                        "type": "criteria",
                        "criteria": {
                            "field": {
                                "api_name": "City"
                            },
                            "comparator": "equal",
                            "value": "Chennai"
                        }
                    },
                    "followup_actions": [
                        {
                            "resources": [
                                {
                                    "name": "Recontact- ${Leads.Last Name} for ${Leads.Company}",
                                    "id": "2276164000000473015"
                                }
                            ],
                            "type": "tasks"
                        }
                    ]
                }
            ],
            "name": "Rule with Followup task",
            "description": "Assigning all Lead records"
        }
    ]
}

Sample Input with type "user"

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

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 task ID. Refer to the Input JSON section for details.
- 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 valid a 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
Resolutions:
- The API name already exists. Specify a unique API names.
- 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 know about edition specific assignment rules creation limits.
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"
        }
    ]
}