Update Territories
Purpose
To update the details of existing territories in your organization.
Request Details
Request URL
{api-domain}/crm/{version}/settings/territories
or
{api-domain}/crm/{version}/settings/territories/{territoryid}
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
scope=ZohoCRM.settings.territories.{operation_type}
Possible operation types
ALL - Full access to territories
UPDATE - To update territories
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v6/settings/territories"
-X PUT
-d "@updateterritories.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"In the request, "@updateterritories.json" contains the sample input.
Input JSON
- id string, optional
Represents the ID of the territory.This is mandatory if ID is not mentioned in the end point
- name string, optional
Represents the name of the territory.
- reporting_to JSON Object, optional
Represents the ID of the parent territory. This can be obtained from GET Territories API
- manager JSON Object, optional
Represents the manager details of the territory.You can give ID of the manager of the territory.Use the Get Users API to get the ID of the user you want to set as manager of the territory.
- permission_type string, mandatory
Represents the type of permission for the territory. Valid values are read_only and read_write_delete.
- description string, optional
Represents the description of the territory.
- account_rule_criteria JSON Object, optional
Represents the criteria for Account module territory rules.
- comparator string, optional
Represents the comparison operator for the account rule criteria (e.g., greater_than, less_than).
- fieldJSON Object, optional
Represents the field details for the account rule criteria.
- api_name string, optional
Represents the API name of the field for the account rule criteria.
- id string, optional
Represents the unique ID of the field for the account rule criteria.This can be obtained from Field Metadata API
- value string, optional
Represents the value to compare with for the account rule criteria.
- lead_rule_criteria JSON Object, optional
Represents the criteria for lead rules in the territory.
- comparator string, optional
Represents the comparison operator for the lead rule criteria (e.g., greater_than, less_than).
- field JSON Object, optional
Represents the field details for the lead rule criteria.
- api_name string, optional
Represents the API name of the field for the lead rule criteria.
- id string, optional
Represents the unique ID of the field for the lead rule criteria. This can be obtained from Field Metadata API
- value string, optional
Represents the value to compare with for the lead rule criteria.
- deal_rule_criteria JSON Object, optional
Represents the criteria for deal rules in the territory.
- comparator string, optional
Represents the comparison operator for the deal rule criteria (e.g., greater_than, less_than).
- field JSON Object, optional
Represents the field details for the deal rule criteria.
- api_name string, optional
Represents the API name of the field for the deal rule criteria.
- id string, optional
Represents the unique ID of the field for the deal rule criteria.This can be obtained from Field Metadata API
- value string, optional
Represents the value to compare with for the deal rule criteria.
Note
The following section describe field types and their allowed comparators
Text, Picklist, Lookup
equal, not_equal, contains, not_contains, starts_with, ends_with
- Date literals supported and their comparators
- Date literal TODAY TOMORROW TOMORROWPLUS(Starting tomorrow) YESTERDAY AGEINDAYS AGEINDAYS EMPTY Comparator equal
- Date literal YESTERDAYMINUS(Till yesterday) Comparator less_equal
- Date literal NOTEMPTY Comparator not_equal
- Date literal LASTMONTH THISMONTH NEXTMONTH LASTWEEK THISWEEK LASTYEAR THISYEAR NEXTYEAR PREVFQ (FQ - Financial Quarter) THISFQ NEXTFQ PREVFY (FY - Financial Year)THISFY NEXTFY Comparator between
- Maximum number of rules supported in each criteria are 25
- Maximum number of territories that can be created in your organiztion depends upon the version of CRM
- Maximum number of territories that can be updated in one API call is 10
Sample Input
Copied{
"territories": [
{
"id": "431581000000798016",
"name": "Territory1234",
"reporting_to": {
"id": "431581000000272796"
},
"manager": null,
"permission_type": "read_only",
"description": null,
"account_rule_criteria": null,
"lead_rule_criteria": null,
"deal_rule_criteria": {
"comparator": "greater_than",
"field": {
"api_name": "Amount",
"id": "431581000000000799"
},
"value": "2000000"
}
}
]
}Possible Errors
- DUPLICATE_DATA HTTP 400
- The territory name given in the request body already exists
- There are duplicate territory names with in the request body.
Resolution: Specify a unique value for territory name for different territories in the body.
- MANDATORY_NOT_FOUND HTTP 400
- The territory ID is not provided in the body for endpoint{api-domain}/crm/{version}/settings/territories
Resolution: Give a valid json request including all mandatory parameters.
- INVALID_DATA HTTP 400
- The parent territory ID is invalid
- The permission_type is invalid
- The reporting_to ID is invalid
- The manager ID is invalid
- The territory name is invalid. The special characters ^ ~ ` # % & + = [ ] { } | \ ; " ' < > , are not allowed.
Resolution: Refer to the "details" key in the response for the API name of the field that has the error in the input. - TERRITORY_NOT_ENABLEDHTTP 403
Territory feature is not enabled
Resolution: Try to enable territory feature. - TERRITORY_DISABLEDHTTP 403
Territory feature is not enabled
Resolution: Try to enable territory feature. - LIMIT_EXCEEDEDHTTP 400
- Maximum Territory limit reached
- Maximum Users Limit reached for a territory
- Maximum Territory Criteria Limit reached
Resolution:Refer to the "details" key in the response for the API name of the field that has the error in the input.
Sample Response
Copied{
"territories": [
{
"code": "SUCCESS",
"details": {
"id": "431581000000798016"
},
"message": "Territory Updated Successfully",
"status": "success"
}
]
}