Assignment Threshold APIs

Assignment Threshold sets an upper limit to the number of records that are assigned to individual users. This automation runs only when records are created by Assignment Rules, Workflow Rules, Blueprint, Macro Actions, Approval Process and Command Centre.

Using Assignment Threshold APIs, you can create, update, retrieve, and delete assignment thresholds, as well as control and monitor user assignment behavior.

Get Assignment Thresholds

Purpose

This API helps you to fetch Assignment Thresholds. You can either fetch all the assignment thresholds configured for a specific module or fetch details of a specific assignment threshold using its unique ID.

Endpoints

GET /settings/automation/assignment_thresholds
GET /settings/automation/assignment_thresholds/{threshold_ID}

{threshold_ID} : ID of the assignment threshold you want to fetch.

Request Details

Request URL

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

To get a specific assignment threshold:
{api-domain}/crm/{version}/settings/automation/assignment_thresholds/{threshold_ID}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.assignment_thresholds.{operation_type}

Possible Operation Types

ALL - Full access to Assignment Threshold data
READ - Fetch existing Assignment Threshold

Parameters

modulestring, optional
Specify the module for which you are want to fetch the assignment thresholds. Use the GET Modules Metadata API to retrieve the module API names.
This parameter is mandatory only when you have to fetch individual assignment thresholds.
Supported Modules: Leads, Contacts, Accounts, Deals, Cases and custom modules.
statusstring, optional
Specify the status of the assignment threshold you want to fetch. The param is applicable only for fetching all assignment thresholds.
Possible Values: active, inactive and all.
filterstring, optional
Specify the filter criteria using which you want to search the configured users of a threshold.
Possible Value:
{
"field": {
"api_name": "{value}"
},
"comparator": "contains",
"value": "{User_name_you_want_to_filter}"
}
- fieldJSON object
  Specify the API name of the field. The only supported value is name.
- comparatorstring
  Specify the comparison operator. The only supported value is contains.
- valuestring
  The value to compare against.
Ensure to encode the filter parameter value before including it in the request URL.

Sample Request

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

Response JSON

The assignment_thresholds array is a root key that contains the list of assignment thresholds based on the request parameters. Each object in the array represents an assignment threshold.

allocation_processJSON object

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

reallocationJSON object
Represents 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
  Contains the type of reallocation method.
  Possible Values: assignment_rule and initial_user.
  If the type is assignment_rule,the name and ID of the assignment rule will be available in the assignment_rule (JSON object) key.
- time_intervalJSON object
  Contains the time interval details after which the reallocation should occur. Following are the supported keys in the object:
  unit : integer - Represents the time unit for the interval.
  period : string - Represents 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.
- next_run_timeDateTime
  Specifies the next scheduled time for reallocation to occur based on the time_interval key values. The date and time is given in ISO 8601 format.

priorityJSON object

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
Represents 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
Contains the unique ID and API name of the field based on which the priority is determined. This key is present only when the type is specific_field.
Supported Field Types: System defined and custom fields with data types - PickList, Date, DateTime, Numeric , Currency , Decimal , Percent, Long integer and checkbox(Boolean).

orderstring

Indicates 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 Type	Sorting Order
String Fields	ascending - A to Z descending - Z to A
Numerical Fields	ascending - Smallest to Largest descending - Largest to Smallest
Boolean / Checkbox Fields	Checkbox and Boolean values are treated as 0 (false/unchecked) and 1 (true/checked). ascending - 0 to 1 descending - 1 to 0

unallocationJSON object
Contains 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
  Indicates the type and related details of unallocation method.
  Possible Values: assignment_rule and round_robin.
  If the type is assignment_rule, the name and ID of the assignment rule will be available in the assignment_rule (JSON object) key.
  If the type is round_robin, details will be available in the round_robin (JSON array) key. Each object in the array contains the following keys:
  type : string - Represents the type of assignee.
  Possible values: user, role, group.
  resource : JSON object - Represents the name and unique ID of the user/role/group.
- time_intervalJSON object
  Indicates the time interval details after which the unallocation should occur. Following are the supported keys in the object:
  unit : integer - Represents the time unit for the interval.
  period : string - Represents 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.
- next_run_timeDateTime
  Specifies the next scheduled time for unallocation to occur based on the time_interval key values. The date and time is given in ISO 8601 format.

created_timeDateTime
Indicates the date and time when the assignment threshold was created. The date and time is given in ISO 8601 format.
moduleJSON object
Represents the module details for which the assignment threshold is configured. The object contains the module name and its unique ID.
activeBoolean
Represents whether the assignment threshold is currently active or inactive.
Possible values:
true - The assignment threshold is active.
false - The assignment threshold is inactive.
created_byJSON object
Represents the user details who created the assignment threshold. The object contains the user's name and their ID.
restrict_toJSON array
Each object in the array contains the threshold details for a user. Following are the keys supported in the object:
- backlog_allow_countinteger
  Contains the maximum number of records allowed for the user to retain in the backlog. New records will not be assigned if the user's backlog count is greater than or equal to the specified value.
- default_assigneeBoolean
  Indicates whether the user is set as the default assignee.
  Possible values:
  true - The user is the default assignee.
  false - The user is not the default assignee.
- record_allow_countinteger
  Represents the maximum number of records that can be assigned to the user for the configured interval period (the record_period key value set using Create Assignment Threshold API).
- record_assigned_countinteger
  Represents the number of records that have been assigned to the user for the configured period.
- typestring
  Represents the type of assignee.
  Possible values: user.
- userJSON object
  Contains the details of the user to whom the threshold is assigned. The object contains the user's name, ID and email address.
- backlog_countinteger
  Represents the number of records that are currently pending or backlogged for the user within the configured period.
backlogJSON object
Contains 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
  Represents the condition for the records to satisfy to qualify as backlog records. Refer to the Create Assignment Threshold API to learn about the supported comparators based on field types and samples for simple and complex criteria.
  The object contains the following keys:
  - fieldJSON object
    Contains the ID and API name of the field on which the criteria is based.
  - comparatorstring
    Represents the comparator to evaluate the criteria.
  - valuestring
    Represents the value to evaluate the exclusion criteria.
  - group_operatorstring
    Contains the logical operator to combine multiple conditions in complex criteria.
    Possible values: and, or.
  - groupJSON array
    Each object in the array represents a condition or a group of conditions in complex criteria.
- records_creation_beforeJSON object
  Indicates 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 - Represents the period for the interval.
  Possible values: days.
  unit : integer - Represents the time unit for the interval.
  Possible values: Following are the possible values that vary based on the record_period value.
  Record Period Unit Possible Values
  day 1-60
  week 7-60
  month 30-60
modified_timeDateTime
Indicates the date and time when the assignment threshold was modified. The date and time is given in ISO 8601 format.
record_periodstring
Represents 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
Contains the criteria to exclude specific records from being considered when evaluating the assignment threshold. Refer to the Create Assignment Threshold API to learn about the supported comparators based on field types and samples for simple and complex criteria.
The object supports the same keys as mentioned in the backlog criteria key.
default_assigneeJSON object
Contains the name and 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.
modified_byJSON object
Represents the user details who modified the assignment threshold. The object contains the user's name and their ID.
idstring
Represents the unique ID of the assignment threshold.
infoJSON object
The object is parallel to the assignment_thresholds key and contains the total count of the users configured in the assignment threshold.

Record Period Unit	Possible Values
day	1-60
week	7-60
month	30-60

Possible Errors

REQUIRED_PARAM_MISSINGHTTP 400
You did not specify the required parameter in the API request.
Resolution: Module parameter is mandatory to fetch 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 404
Invalid assignment threshold ID is provided in the request URL.
Resolution: Always provide a valid assignment threshold ID. Make an overall GET Assignment Threshold API to retrieve assignment threshold IDs.
NO_PERMISSIONHTTP 403
You do not have enough permission to fetch assignment threshold for users.
Resolution: Contact your CRM administrator.
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.
NOT_SUPPORTEDHTTP 400
You provided an invalid module in the API request.
Resolution: Assignment Threshold is supported only for Leads, Contacts, Accounts, Deals, Cases and custom modules. Specify a valid module name 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.
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 fetch 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": [
        {
            "allocation_process": {
                "reallocation": {
                    "method": {
                        "assignment_rule": {
                            "name": "ThresholdRule",
                            "id": "1862079000003431003"
                        },
                        "type": "assignment_rule"
                    },
                    "next_run_time": "2025-12-24T22:09:14+05:30",
                    "time_interval": {
                        "unit": 2,
                        "period": "hours"
                    }
                },
                "priority": {
                    "type": "fifo"
                },
                "unallocation": {
                    "method": {
                        "round_robin": [
                            {
                                "resource": {
                                    "name": "Manager",
                                    "id": "1862079000000015969"
                                },
                                "type": "role"
                            }
                        ],
                        "type": "round_robin"
                    },
                    "next_run_time": "2025-12-27T16:08:48+05:30",
                    "time_interval": {
                        "unit": 4,
                        "period": "days"
                    }
                }
            },
            "created_time": "2025-12-23T16:08:48+05:30",
            "module": {
                "api_name": "Leads",
                "id": "1862079000000000125"
            },
            "active": true,
            "created_by": {
                "name": "Patricia Boyle",
                "id": "1862079000000440001"
            },
            "restrict_to": [
                {
                    "backlog_allow_count": 10,
                    "default_assignee": false,
                    "record_allow_count": 10,
                    "record_assigned_count": 0,
                    "type": "user",
                    "user": {
                        "name": "Patricia Boyle",
                        "id": "1862079000000440001",
                        "email": "patricia.boyle+2@zylker.com"
                    },
                    "backlog_count": 20
                },
                {
                    "backlog_allow_count": 5,
                    "default_assignee": false,
                    "record_allow_count": 10,
                    "record_assigned_count": 0,
                    "type": "user",
                    "user": {
                        "name": "Tresa Sweely",
                        "id": "1862079000000585110",
                        "email": "tresa.sweely@zylker.com"
                    },
                    "backlog_count": 0
                }
            ],
            "backlog": {
                "records_creation_before": {
                    "period": "days",
                    "unit": 7
                }
            },
            "modified_time": "2025-12-24T20:26:42+05:30",
            "record_period": "week",
            "exclude_criteria": {
                "group_operator": "AND",
                "group": [
                    {
                        "comparator": "equal",
                        "field": {
                            "api_name": "Country",
                            "id": "1862079000000000611"
                        },
                        "type": "value",
                        "value": "India"
                    },
                    {
                        "comparator": "equal",
                        "field": {
                            "api_name": "City",
                            "id": "1862079000000000605"
                        },
                        "type": "value",
                        "value": "Mumbai"
                    }
                ]
            },
            "default_assignee": {
                "name": "Theola Frey",
                "id": "1862079000011223003"
            },
            "modified_by": {
                "name": "Patricia Boyle",
                "id": "1862079000000440001"
            },
            "id": "1862079000024556062"
        }
    ],
    "info": {
        "total_count": 2
    }
}