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 POSTInput 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"
}
]
}