Validate User Threshold for Record

Purpose

This API helps you to validate the assignment threshold limit for users in a specific module based on the record details. The limit will be calculated based on the backlog count and the record assigned count for the specified user.

Additionally, you can also check whether the user can be assigned this particular record according to the Exclude Criteria defined in the assignment threshold settings.

Endpoints

  • GET /{module_API_name}/{record_ID}/actions/permit_threshold
  • {module_API_name} : API name of the module for which you want to check the assignment threshold limit.
  • {record_ID} : ID of the record for which you want to check the assignment threshold limit of the user.

Request Details

Request URL

{api-domain}/crm/{version}/{module_API_name}/{record_ID}/actions/permit_threshold

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52 

Scope

ZohoCRM.modules.{operation_type} or
ZohoCRM.modules.{module_API_name}.{operation_type}

Possible Operation Types

ALL - Full access to modules data
READ - Fetch modules data

Supported Modules

Leads, Contacts, Accounts, Deals, Cases and custom modules. 

Custom Modules

For custom modules, use their respective API names in the request URL. You can obtain the API name from Setup -> Developer Hub -> APIs & SDKs -> API Names. You can also get the module API name from the api_name key in the GET Modules Metadata API's response. 

Parameters

  • owner_idstring, mandatory

    ID of the user for whom you want to validate the assignment threshold limit. Use the GET Users API to get the user ID.

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/Leads/1862079000022190065/actions/permit_threshold?owner_id=111111000000056029"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Response JSON

  • The permit_threshold object is the root key that contains the details of the assignment threshold validation for the specified user against a specific record.

    allowBoolean

    Indicates whether the assignment threshold has been reached for the user and whether the user is permitted to be assigned new records. 
    Possible values: 
    true - The assignment threshold has not been reached. 
    false - The assignment threshold has been reached.

  • reasonstring

    Provides the reason for permitting or not permitting the user from being assigned new records.

    Possible Values:

    • RECORD_ALLOWED: The record is permitted to be assigned to the user.
    • RECORD_DENIED_BY_BACKLOG: The user threshold for backlog has been reached and the user is not permitted to be assigned new records.
    • RECORD_DENIED_BY_ALLOWCOUNT: The user threshold for allowed count has been reached and the user is not permitted to be assigned new records.
    • NO_RESTRICTION: The user does not have any assignment threshold configured.
    • RESTRICTION_DISABLED: The assignment threshold for the user is disabled or deactivated.
    • RECORD_EXCLUDED: The record meets the exclude criteria defined in the assignment threshold settings and is permitted to be assigned to the user.
  • remaining_allow_countinteger

    Represents the number of additional records that can be assigned to the user before reaching the assignment threshold limit.

Possible Errors

  • REQUIRED_PARAM_MISSINGHTTP 400

    You did not specify the required parameter in the API request. 
    Resolution: owner_id parameter is mandatory to validate assignment threshold for a user. Make a GET Users API call to get the user ID and specify it in the parameter.

  • INVALID_DATAHTTP 400

    Invalid record ID is provided in the request URL. 
    Resolution: Always provide a valid record ID. Make a GET Records API call to get the valid record ID.

  • NO_PERMISSIONHTTP 403

    You do not have enough permission to validate assignment threshold for users against a specific record. 
    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 validate an assignment threshold for a user against a specific record. 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{
    "permit_threshold": {
        "allow": true,
        "reason": "RECORD_ALLOWED",
        "remaining_allow_count": 10
    }
}