Update Territories

Purpose

To update the details of existing territories in your Zoho CRM organization.

Endpoints

PUT /settings/territories
PUT /settings/territories/{territory_ID}

Request Details

Request URL

To update all territories:
{api-domain}/crm/{version}/settings/territories

To update a specific territories:
{api-domain}/crm/{version}/settings/territories/{territory_ID}

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

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/v8/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. Set the manager field to null to remove a manager from 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 (For example, 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 (For example, 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

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.
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 keys name, reporting_to and permission_type are mandatory parameters
  Resolution: Give a valid json request including all mandatory parameters.
- The manager field is set as an empty JSON Object
  Resolution: Give a valid value for the manager field.
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.
- The given Criteria is not a valid JSON
Resolution: Refer to the "details" key in the response for the API name of the field that has the error in the input.
NOT_ALLOWEDHTTP 400
- Cannot update the Org Territory except Name
  Resolution: You cannot update the organization territory except for the name.
- Territory Deal Rule Disabled
  Resolution: You cannot update the deal rule when territory deal rule is disabled.
- Territory Lead Rule Disabled
  Resolution: You cannot update the lead rule when territory deal rule is disabled.
PERMISSION_DENIEDHTTP 400
User does not have permission to view/access the Territory
Resolution: The user does not have permission to update territories. Contact your system administrator.
OAUTH_SCOPE_MISMATCHHTTP 401
The access token you have used to make this API call does not have the required scope
Resolution: Generate a new access token with the required scopes for this API. Refer to Scope section at the beginning of this page for the list of required scopes.
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.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect
Resolution: Specify a valid request URL. Refer to request URL section at the beginning of this page for more details.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server
Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "territories": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "431581000000798016"
            },
            "message": "Territory Updated Successfully",
            "status": "success"
        }
 ]
}