Create Assignment Threshold

Purpose

This API helps you to create Assignment Thresholds to set an upper limit to the number of records that are assigned to individual users.

Endpoints

  • POST /settings/automation/assignment_thresholds

Request Details

Request URL

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

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52 

Scope

ZohoCRM.settings.assignment_thresholds.{operation_type}

Possible Operation Types

ALL - Full access to Assignment Threshold data
CREATE - Create new Assignment Threshold

Parameters

  • modulestring, mandatory

    Specify the module for which the assignment threshold should be applied. Use the GET Modules Metadata API to retrieve the module API names. 
    Supported Modules: Leads, Contacts, Accounts, Deals, Cases and custom modules.

Sample Request

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

Input JSON

  • The request body must contain the assignment_thresholds array key. You can include only one object in this array per request. Following are the keys supported in the object:

    restrict_toJSON array, mandatory

    Provide the threshold details for an individual user in each object of the array. Following are the keys supported in the object:

    • record_allow_countinteger, mandatory

      Specify the maximum number of records that can be assigned to the user for the configured interval period (use the record_period key to set the period). You can assign the record count of up to 999,999.

    • backlog_allow_countinteger, optional

      Specify the maximum number of records allowed for the user to retain in the backlog. You can assign the backlog count of up to 999,999 and the default value is null.

      New records will not be assigned if the user's backlog count is greater than or equal to the specified value.

    • userJSON object, mandatory

      In the object, provide the unique ID of the user for whom the assignment threshold is being created. Use the GET Users API to retrieve user IDs.

    • typestring, mandatory

      Specify the type of assignee. 
      Possible values: user.

    Note

    • You can add up to 500 users in the restrict_to list while creating an assignment threshold.
    • If a threshold is configured for the same user as the default_assignee, the threshold configuration for that user in the restrict_to list will be overridden and the default assignee will be applied.
  • record_periodstring, mandatory

    Specify the duration over which the system enforces the threshold value, which is the record_allow_count.
    Possible values: day, week and month.

  • exclude_criteriaJSON object, optional

    Provide the criteria to exclude specific records from being considered when evaluating the assignment threshold. Following is the syntax for simple and complex criteria:

    Simple Criteria: 
    Simple criteria involves a single condition. For example, to exclude records where the Country is India:

    {
       "field": {
           "api_name": "Country"
       },
       "comparator": "equal",
       "value": "India"
    }

    Complex Criteria: 
    Complex criteria involves multiple conditions combined using logical operators. For example, to exclude records where the Country is India and the City is Mumbai or the Annual Revenue is 500000 (Pattern: ( ( 1 and 2 ) or 3 )) :

    {
       "group_operator": "or",
       "group": [
           {
               "group_operator": "and",
               "group": [
                   {
                       "field": {
                           "api_name": "Country"
                       },
                       "comparator": "equal",
                       "value": "India"
                   },
                   {
                       "field": {
                           "api_name": "City"
                       },
                       "comparator": "equal",
                       "value": "Mumbai"
                   }
               ]
           },
           {
               "field": {
                   "api_name": "Annual_Revenue"
               },
               "comparator": "equal",
               "value": "500000"
           }
       ]
    }

    • fieldJSON object, mandatory

      Provide the API name of the field on which the exclusion criteria is based. Use the GET Fields Metadata API to get the field API name.

    • comparatorstring, mandatory

      Specify the comparator to evaluate the exclusion criteria. Following are the supported comparators based on field types:

      Field TypeComparator
      Text/Text Area, Email, Phone, Website, Picklist, Multi-select Picklist, Auto-number, Currencyequal, not_equal, contains, not_contains, starts_with, ends_with
      Date, Datetimeequal, not_equal, less_than, greater_than, between, not_between, less_equal, greater_equal
      Integer, Double, Bigint, Lookupequal, not_equal, less_than, less_equal, greater_than, greater_equal, between, not_between
      Booleanequal
      User Lookupin, not_in
      FormulaComparator will depend on the return type.
    • valuestring, mandatory

      Specify the value to evaluate the exclusion criteria.

    • group_operatorstring, optional

      Specify the logical operator to combine multiple conditions in complex criteria.
      Possible values: and, or.

    • groupJSON array, optional

      Each object in the array represents a condition or a group of conditions in complex criteria.

  • default_assigneeJSON object, mandatory

    Provide the unique ID of the fallback user to whom the remaining records should be assigned once every user in the restrict_to list reaches their assignment threshold. Use the GET Users API to retrieve user IDs.

    Note

    If a threshold is configured for the same user as the default_assignee, the threshold configuration for that user in the restrict_to list will be overridden and the default assignee will be applied.

  • backlogJSON object, optional

    Specify the details of the backlog criteria and the time after which the current records with a user should be considered for backlog count.

    • criteriaJSON object, mandatory

      Provide the condition for the records to satisfy to qualify as backlog records. All the keys supported in the exclude_criteria can be used here.

    • records_creation_beforeJSON object, mandatory

      Provide the time interval details after which the current records with a user should be considered for backlog count. Following are the supported keys in the object:

      period : string, mandatory - Specify the period for the interval. 
      Possible values: days.

      unit : integer, mandatory - Specify the time unit for the interval.
      Possible values: Following are the possible values that vary based on the record_period value.

      Record Period UnitPossible Values
      day1-60
      week7-60
      month30-60
  • allocation_processJSON object, optional

    Specify the details of the priority, reallocation and unallocation process for the assignment threshold.

    Each process supports different behaviors. Based on the selected behavior, the set of supported keys within that process may vary. 
    The code samples provided for each process demonstrate the alternative behavior that is not shown in the initial example.

    Following are the supported keys in each process:

    • priorityJSON object, mandatory

      This object defines the priority order in which records are reallocated or unallocated to a different user after reaching the configured time interval. Following are the supported keys in the object:

      • typestring, mandatory

        Specify the type of priority.
        Possible values: specific_field, fifo.

        • specific_field: The records will be prioritized based on the values in a specific field. The field details will be available in the field key.
        • fifo: The records will be reallocated based on the order in which they were created, with the oldest record being reallocated first.
      • fieldJSON object, mandatory when type is specific_field

        Provide the unique ID and API name of the field based on which the priority is determined. Field ID is a mandatory key in the object. Use the GET Fields Metadata API to get the field details.

        Supported Field Types: System defined and custom fields with data types - PickList, Date, DateTime, Numeric , Currency , Decimal , Percent, Long integer and checkbox(Boolean).

      • orderstring, mandatory when type is specific_field

        Specifies the order in which the field values should be evaluated for priority. 
        Possible values: ascending and descending.

        Following is a table that helps you to understand how the order works based on field types:

        Field TypeSorting Order
        String Fieldsascending - A to Z 
        descending - Z to A
        Numerical Fieldsascending - Smallest to Largest 
        descending - Largest to Smallest
        Boolean / Checkbox FieldsCheckbox and Boolean values are treated as 0 (false/unchecked) and 1 (true/checked). 
        ascending - 0 to 1 
        descending - 1 to 0
    • reallocationJSON object, mandatory

      Provide the details for the reallocation of records from the default assignee to the users in the restrict_to list after the configured time interval.

      • methodJSON object, mandatory

        Give the type of reallocation method. 
        Possible Values: assignment_rule and initial_user.

        If the type is assignment_rule, you need to specify the ID of the assignment rule in the assignment_rule (JSON object) key. Use the GET Assignment Rules API to retrieve the assignment rule ID.

      • time_intervalJSON object, mandatory

        Provide the time interval details after which the reallocation should occur. Following are the supported keys in the object:

        unit : integer, mandatory - Specify the time unit for the interval.
        period : string, mandatory - Specify the period for the interval. 
        Possible values: hours, days, minutes, business_hours and business_days. For minutes, the supported values are 15, 30 and 45.

    • unallocationJSON object, mandatory

      Provide the details for the unallocation of records from the default_assignee to the users in the restrict_to list after the configured time interval.

      • methodJSON object, mandatory

        Specify the type and related details of unallocation method. 
        Possible Values: assignment_rule and round_robin.

        If the type is assignment_rule, you need to specify the ID of the assignment rule in the assignment_rule (JSON object) key. Use the GET Assignment Rules API to retrieve the assignment rule ID.

        If the type is round_robin, specify the details in the round_robin (JSON array) key. Each object in the array should contain the following keys:

        type : string, mandatory - Specify the type of assignee. 
        Possible values: user, role, group. 
        resource : JSON object, mandatory - Provide the unique ID of the user/role/group. Use the GET Users API to retrieve user IDs.

        Note

        • You cannot provide multiple types in the round_robin array.
        • You can add only one group or role to the resource key, but you can add multiple users.
      • time_intervalJSON object, mandatory

        Provide the time interval details after which the unallocation should occur. The unallocation time interval must be greater than the reallocation time interval.

        Following are the supported keys in the object:

        unit : integer, mandatory - Specify the time unit for the interval.
        period : string, mandatory - Specify the period for the interval. 
        Possible values: hours, days, minutes, business_hours and business_days. For minutes, the supported values are 15, 30 and 45.

Note

  • The time interval provided for the unallocation must be greater than the reallocation time interval.
  • The reallocation and unallocation time intervals must be configured using the same period type, either normal timings or business timings.

Sample Input

Copied{
    "assignment_thresholds": [
        {
            "restrict_to": [
                {
                    "record_allow_count": 10,
                    "backlog_allow_count": 5,
                    "user": {
                        "id": "111111000000057843"
                    },
                    "type": "user"
                }
            ],
            "module": {
                "api_name": "Leads"
            },
            "record_period": "day",
            "exclude_criteria": {
                "field": {
                    "api_name": "City",
                    "id": "111111000000004924"
                },
                "comparator": "equal",
                "value": "Chennai",
                "type": "value"
            },
            "default_assignee": {
                "id": "111111000000077783"
            },
            "allocation_process": {
                "priority": {
                    "type": "specific_field",
                    "order": "descending",
                    "field": {
                        "id": "111111000000004846"
                    }
                },
                "reallocation": {
                    "method": {
                        "type": "initial_user"
                    },
                    "time_interval": {
                        "unit": 2,
                        "period": "hours"
                    }
                },
                "unallocation": {
                    "method": {
                        "type": "assignment_rule",
                        "assignment_rule": {
                            "id": "111111000000125002",
                            "name": "1234"
                        }
                    },
                    "time_interval": {
                        "unit": 20,
                        "period": "hours"
                    }
                }
            },
            "backlog": {
                "criteria": {
                    "field": {
                        "api_name": "Annual_Revenue",
                        "id": "111111000000004846"
                    },
                    "comparator": "equal",
                    "value": "1234567890",
                    "type": "value"
                },
                "records_creation_before": {
                    "unit": 2,
                    "period": "days"
                }
            }
        }
    ]
}

Sample input with priority set to specific_field, reallocation type set to initial_user, and unallocation type set to assignment_rule.

Sample Input with Different Allocation Process

Copied{
    "assignment_thresholds": [
        {
            "restrict_to": [
                {
                    "record_allow_count": 10,
                    "backlog_allow_count": 5,
                    "user": {
                        "id": "111111000000057843"
                    },
                    "type": "user"
                }
            ],
            "module": {
                "api_name": "Leads"
            },
            "record_period": "day",
            "exclude_criteria": {
                "field": {
                    "api_name": "City",
                    "id": "111111000000004924"
                },
                "comparator": "equal",
                "value": "Chennai",
                "type": "value"
            },
            "default_assignee": {
                "id": "111111000000077783"
            },
            "allocation_process": {
                "priority": {
                    "type": "fifo"
                },
                "reallocation": {
                    "method": {
                        "type": "assignment_rule",
                        "assignment_rule": {
                            "id": "1862079000003431003"
                        }
                    }
                },
                "unallocation": {
                    "method": {
                        "type": "round_robin",
                        "round_robin": [
                            {
                                "type": "role",
                                "resource": {
                                    "id": "1862079000000015969"
                                }
                            }
                        ]
                    },
                    "time_interval": {
                        "unit": 4,
                        "period": "days"
                    }
                }
            },
            "backlog": {
                "criteria": {
                    "field": {
                        "api_name": "Annual_Revenue",
                        "id": "111111000000004846"
                    },
                    "comparator": "equal",
                    "value": "1234567890",
                    "type": "value"
                },
                "records_creation_before": {
                    "unit": 2,
                    "period": "days"
                }
            }
        }
    ]
}

Sample input with priority set to fifo, reallocation type set to assignment_rule, and unallocation type set to round_robin.

Possible Errors

  • REQUIRED_PARAM_MISSINGHTTP 400

    You did not specify the required parameter in the API request. 
    Resolution: Module parameter is mandatory to create an assignment threshold. Make a GET Modules Metadata API call to get the valid module API names and specify the valid module name in the parameter.

  • INVALID_DATAHTTP 400

    • Invalid user ID is provided in the restrict_to or default_assignee key.

      Resolution: Always provide a valid user ID. Use the GET Users API to retrieve user IDs.

    • Invalid user ID is given in the round_robin key.

      Resolution: Fetch the valid user ID to use in the round_robin key. Refer to the GET Users API to retrieve user IDs.

    • Invalid Assignment Rule ID is provided in the method key for either reallocation or unallocation.

      Resolution: Always get the valid assignment rule ID from the GET Assignment Rules API and provide it in the method key.

    • Invalid field ID is provided in the Priority key.

      Resolution: Fetch the valid field ID using GET Fields Metadata API to use in the priority key.

    • Invalid value is specified in the period key for reallocation or unallocation time interval.

      Resolution: Ensure to use only the supported values for the period key - hours, days, minutes, business_hours and business_days. For minutes, the supported values are 15, 30 and 45.

    • Invalid value is specified in the period key for records_creation_before.

      Resolution: You can use only days in the period key for records_creation_before. The value for unit key is based on the record_period value as mentioned in the Input JSON section.

  • NO_PERMISSIONHTTP 403

    You do not have enough permission to create assignment threshold for users. 
    Resolution: Contact your CRM administrator.

  • NOT_ALLOWEDHTTP 400

    • The user specified in the restrict_to key already has an active assignment threshold in the module.

      Resolution: Make a GET Assignment Threshold API call to the same module. Check the existing assignment thresholds and its corresponding users in the restrict_to key. Remove those users from the restrict_to list or delete the existing assignment threshold using the DELETE Assignement Threshold API before creating the new threshold.

    • You are not allowed to set assignment threshold for System and Support users.

      Resolution: Assignment threshold is not applicable for System and Support users. Make a GET Users API call and use the user IDs with type__s as Regular User.

    • You are not allowed to set System or Support users as default_assignee.

      Resolution: Make a GET Users API call and use the user IDs with type__s as Regular User.

    • You are not allowed to set System or Support users in the round_robin key.

      Resolution: Make a GET Users API call and use the user IDs with type__s as Regular User.

    • You cannot provide more than one entry when type is role or group in the round_robin key.

      Resolution: You can add only one group or role to the resource key, but you can add multiple users in the round_robin key.

  • MANDATORY_NOT_FOUNDHTTP 400

    One or more mandatory keys are missing.
    Resolution: Specify all the mandatory keys to create an assignment threshold for users. Refer to the Input JSON section to know the mandatory keys.

  • DEPENDENT_MISMATCHHTTP 400

    • The unallocation time interval is less than or equal to the reallocation time interval.

      Resolution: The time interval provided for the unallocation must be greater than the reallocation time interval.

    • You cannot provide different time period types for reallocation and unallocation time intervals.

      Resolution: Both the reallocation and unallocation time intervals should be set to either normal timings or business timings.

  • AMBIGUITY_DURING_PROCESSINGHTTP 400

    • You specified an invalid field ID or API Name in the priority key.

      Resolution: Specify a valid field ID or API Name in the priority key. Use the GET Fields Metadata API to get the field details.

    • You provided different types in the round_robin key.

      Resolution: For the round_robin key, you cannot provide multiple types. You can give only one type among user, role or group. Also, you cannot add multiple entries for roles and groups but can add multiple entries for user.

  • INVALID_MODULEHTTP 400

    You provided an invalid module name in the API request.
    Resolution: Make a GET Modules Metadata API call to get the valid module name and specify it in the parameter.

  • FEATURE_NOT_SUPPORTEDHTTP 400

    Your CRM edition does not support this feature.
    Resolution: Assignment Threshold is supported in Professional and above editions. Upgrade your CRM edition to use this feature.

  • API_NOT_SUPPORTEDHTTP 400

    You specified an invalid or lower version in the API request.
    Resolution: Assignment Threshold is supported from API version v8 and above. Specify a valid version in the API request.

  • LICENSE_LIMIT_EXCEEDEDHTTP 400

    You have exceeded the license limit for Assignment Threshold.
    Resolution: Upgrade your license to increase the limit for Assignment Threshold. Refer to the Zoho CRM Edition page to know the limits for each 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 the endpoints section of the API.

  • OAUTH_SCOPE_MISMATCHHTTP 401

    Unauthorized
    Resolution: The client does not have a valid scope to create an assignment threshold. Create a new token with valid scope. Refer to scope section of the API.

  • 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 the request URL section of the API.

  • INTERNAL_ERRORHTTP 500

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

Sample Response

Copied{
    "assignment_thresholds": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "2000000119037"
            },
            "message": "assignment threshold created successfully",
            "status": "success"
        }
    ]
}