Create Scoring Rules

The Create Scoring Rules API allows you to define scoring rules that can be applied to specific layouts or globally across all layouts within your Zoho CRM organization. Scoring rules can be constructed using either field rules, signal rules, or a combination of both. Refer to Multiple Scoring Rules to learn more about scoring rules.

The following table outlines the availability and limitations of scoring rules based on different editions of Zoho CRM.

Supported Editions and Limits:

Edition	Multiple Layout Support	Active Rules per Module	Total Rules per Module	Number of Criteria per Rule
Standard (S)	NO	1	1	10
ZohoOne Standard (Y)	NO	1	1	10
Professional (P, R)	NO	1	1	20
Developer (D)	YES - 2 layouts	15	30	5
Enterprise (E, A)	YES - 4 layouts	25	50	30
ZohoOne Enterprise (Z)	YES - 4 layouts	25	50	30
CrmPlus (C)	YES - 7 layouts	40	80	50
Ultimate (U)	YES - 7 layouts	40	80	50

Purpose

To create a scoring rule for a module in the Zoho CRM organization.

Note

Only Leads, Contacts, and other people-based modules support signal rules. Non-people modules such as Deals and Accounts do not support signal rules.

Endpoints

POST /settings/automation/scoring_rules

Request Details

Request URL

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

Supported modules

Leads, Accounts, Contacts, Deals and Custom

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.scoring_rules.ALL
(or)
ZohoCRM.settings.scoring_rules.{operation_type}

Possible operation types

ALL - Full access to scoring rules
CREATE - Create scoring rules

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/automation/scoring_rules"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @createrules.json
-X POST

Input JSON

scoring_rulesJSON array, mandatory
An array containing the scoring rule objects.
namestring, mandatory
Represents the unique name of the scoring rule. The maximum possible length for this field is 25 characters.
moduleJSON object, mandatory
Represents the module for which the scoring rule is defined. This object must include the ID and the API name of the module.
descriptionstring, optional
Represents the description of the scoring rule. The maximum possible length for this field is 500 characters.
layoutJSON object, optional
Represents the layout the scoring rule is associated with. This object must include the ID and the API name of the layout.
activeBoolean, optional
Indicates whether the scoring rule is active.
Possible values :
true - The rule is active. This is the default value.
false - The rule is inactive.
field_rulesJSON array, optional if signal_rules is specified
An array of field rule objects associated with the scoring rule. Each field rule must include:
- scorenumber, mandatory
  Represents the score assigned for the specific rule. The value of this keys ranges from -100 to 100.
- criteriaJSON object, mandatory
  Represents the criteria details, including:
  - group_operatorstring, mandatory
    The logical operator used to combine criteria. Possible values are and or or.
  - groupJSON array, mandatory
    An array of criteria objects that define the conditions for scoring. Each criterion must include:
    - fieldJSON object, mandatory
      Specify the field being evaluated.
    - comparator stringstring, mandatory
      The comparison operator. The supported operators are equals, starts_with, in, not_equal, greater_equal, greater_than, less_equal, less_than and between.
    - valuestring, mandatory
      The value to compare the field value against.
signal_rulesJSON array, optional if field_rules is specified
An array of signal rule objects defined for this scoring rule. Each signal rule must include:
- scorenumber, mandatory
  The score assigned to this signal rule. The value of this keys ranges from -100 to 100.
- signalJSON object, mandatory
  Represents the signal details. You can get the signal details using the Signals API.
  - namespacestring, mandatory
    The namespace of the signal.
  - idstring, mandatory
    The unique identifier for the signal.
custom_fieldsJSON array, optional
An array of custom field objects that allow users to create new fields or map scores to existing fields in records. Each custom field includes:
- field_labelstring, mandatory
  The label for the custom field as it will appear in the user interface. If you want to use an exisiting field, use the field label of the corresponding field.
- reference_fieldJSON object, mandatory
  To map the custom field to a specific score.
  - api_namestring, mandatory
    The API name of the score that you want to map. The possible values are Positive_Score, Negative_Score, Touch_Point_Score, Touch_Point_Positive_Score, Touch_Point_Negative_Score and Score.

Note

At least one of either field_rules or signal_rules must be specified.

Custom Fields Limit for Scoring Rules

The following table outlines the maximum number of custom fields that can be created for scoring rules, based on the edition of Zoho CRM you are using. The maximum number of fields you can add for one scoring rule is six, irrespective of the edition. Please note that the custom fields must remain within the integer custom fields limit of the respective module.

Edition	Limit
Standard (S)	6
Zoho One Standard (Y)	6
Professional (P, R)	6
Developer (D)	6
Enterprise (A, E)	30
Zoho One Enterprise (Z)	30
CRM Plus (C)	30
Ultimate (U)	30

Note

Any custom field created while creating a scoring rule will be deleted when the scoring rule itself is deleted.

Sample Input

Copied{
    "scoring_rules": [
        {
            "name": "Rule 01",
            "description": "Rule for Module Leads",
            "module": {
                "id": "4876876000000002175",
                "api_name": "Leads"
            },
            "layout": {
                "id": "4876876000000091055",
                "api_name": "Standard"
            },
            "active": false,
            "field_rules": [
                {
                    "score": 10,
                    "criteria": {
                        "group_operator": "OR",
                        "group": [
                            {
                                "field": {
                                    "api_name": "Company"
                                },
                                "comparator": "equal",
                                "value": "zoho"
                            },
                            {
                                "field": {
                                    "api_name": "Designation"
                                },
                                "comparator": "contains",
                                "value": "review"
                            }
                        ]
                    }
                },
                {
                    "score": 10,
                    "criteria": {
                        "group_operator": "OR",
                        "group": [
                            {
                                "field": {
                                    "api_name": "Company"
                                },
                                "comparator": "not_equal",
                                "value": "Zylker"
                            },
                            {
                                "field": {
                                    "api_name": "Designation"
                                },
                                "comparator": "equal",
                                "value": "review"
                            }
                        ]
                    }
                }
            ],
            "signal_rules": [
                {
                    "score": 10,
                    "signal": {
                        "namespace": "Email_Incoming__s",
                        "id": "4876876000000112019"
                    }
                },
                {
                    "score": 8,
                    "signal": {
                        "namespace": "EmailInsight_Click__s",
                        "id": "4876876000000112023"
                    }
                }
            ],
            "custom_fields": [
                {
                    "field_label": "Positive Total",
                    "reference_field": {
                        "api_name": "Positive_Score"
                    }
                },
                {
                    "field_label": "Touchpoint Positive",
                    "reference_field": {
                        "api_name": "Touch_Point_Positive_Score"
                    }
                }
            ]
        }
    ]
}

Possible Errors

INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP POST method to make this API call. Any other request method will result in this error.
INVALID_DATAHTTP 400
You have specified an invalid or unsupported module, or an invalid layout.
Resolution: Specify valid module and layout details.
INVALID_DATAHTTP 400
You have either specified a rule name exceeding 25 characters or description exceeding 500 characters.
Resolution: Please specify the name and description within their respective limits of 25 characters and 500 characters.
MANDATORY_NOT_FOUNDHTTP 400
You have not specified a mandatory field in the input.
Resolution: Please specify all mandatory fields. Refer to the input JSON section to know more.
EXPECTED_FIELD_MISSINGHTTP 400
You have not specified fields rule or signal rule.
Resolution: Specify the field rules and/or signal rules to create the scoring rule.
DUPLICATE_DATAHTTP 400
A scoring rule with the specified criteria or the same name already exists
Resolution: Specify a different criterion or name for the rule.
ALREADY_USEDHTTP 400
The specified criteria is already given in the same rule under different index.
Resolution: Please specify a different criteria.
NOT_SUPPORTEDHTTP 400
You have specified Signal rules for non-people module. Signal rules are not supported for non-people modules.
Resolution: Use field rules for the specified module.
INVALID_DATAHTTP 400
You have specified an invalid value for the score key. Specify a valid value for the key.
Resolution: Please refer to input JSON section for more details.
ACTIVE_STATE_LIMIT_EXCEEDEDHTTP 400
You have exceeded the number of active rules possible for your account.
Resolution: Limit the number of active rules within the permissible limit. Refer to the feature limits table at the beginning of this page for more details.
LIMIT_EXCEEDEDHTTP 400
You have already created the maximum number of scoring rules possible.
Resolution: Limit the number of rules within the maximum possible limit. Refer to the feature limits table at the beginning of this page for more details.
FEATURE_NOT_SUPPORTEDHTTP 400
You are trying to create multiple scoring rules for an unsupported edition.
Resolution: Contact system administrator.
NOT_SUPPORTEDHTTP 400
Given field is not available with the given layout.
Resolution: Specify fields available in the given layout.
NOT_SUPPORTEDHTTP 400
Layout or score fields is specified in the criteria.
Resolution: Specify valid fields in the criteria.
OAUTH_SCOPE_MISMATCHHTTP 401
The access token you have used to make this API call does not have the required scope.
Resolution: Generate a new access token with the required scopes for this API. Refer to the Scope section at the beginning of this page for the list of required scopes.
NO_PERMISSIONHTTP 403
You do not have permission to create scoring rules.
Resolution: The user does not have permission to create scoring rules. Contact your system administrator.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the request URL section at the beginning of this page for more details.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "scoring_rules": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "4876876000009019118"
            },
            "message": "scoring rule created successfully",
            "status": "success"
        }
    ]
}