Create Scoring Rules

Scoring rules can be layout-specific or global rules that can be applied to all layouts. A scoring rule can be defined using both field rules and signal rules, or just one of them. The limitations regarding the number of rules per module, number of active rules for different editions and more are explained here.

Purpose

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

Note

Only leads and contacts (the people modules) can have signal rules. The non-people modules (Deals, Accounts and Custom Modules) do not support signal 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

scope=ZohoCRM.settings.scoring_rules.ALL
(or)
scope=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/v4/settings/automation/scoring_rules"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @createrules.json
-X POST

Input JSON Keys

  • namestring, mandatory

    Represents the unique name of the current scoring rule. The maximum possible length for this field is 25 characters.

  • descriptionstring, optional

    Represents the description of the current rule. The maximum possible length for this field is 500 characters.

  • moduleJSON object, mandatory

    Represents the module the scoring rule is defined for.

  • layoutJSON object, optional

    Represents the layout the rule is associated with.

  • activeBoolean, optional

    Represents whether the current scoring rule is active or not. Default value is true.

  • field_rulesJSON array, optional

    Represents the field rules for the scoring rule.

  • scorenumber, mandatory

    Represents the score assigned for the specific rule. The value of this keys ranges from -10 to 10.

  • criteriaJSON object, mandatory

    Represents the rule criteria details.

  • group_operatorstring, mandatory

    Represents the operator. Possible values are and or or.

  • groupJSON array, mandatory

    Represents the fields to be joined using the group operator for the current criterion.

  • signal_rulesJSON array, optional

    Represents the signal rules defined.

Sample Input

Copied{
   "scoring_rules":[
      {
         "name":"Rule 9",
         "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":"equal",
                        "value":"review"
                     }
                  ]
               }
            }
         ]
      }
   ],
   "signal_rules":[
      {
         "score":10,
         "signal":{
            "namespace":"Email_Incoming__s",
            "id":"1000000000037"
         }
      },
      {
         "score":8,
         "signal":{
            "namespace":"EmailInsight_Click__s",
            "id":"1000000000038"
         }
      }
   ]
}

Possible Errors

  • 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 above.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    Unauthorized
    Resolution: Client does not have ZohoCRM.settings.scoring_rules.CREATE scope. Create a new client with valid scope. Refer to scope section above for more details.

  • NO_PERMISSIONHTTP 403

    Permission denied to create
    Resolution: The user does not have permission to create scoring rules. Contact your system administrator.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error
    Resolution: Unexpected and unhandled exception in Server. Contact support team.

  • 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 above.

  • 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 keys 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 keys 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 the limits 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. Please refer to the Get Scoring Rules 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.

Sample Response

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