Update Territories

Purpose

To update the details of existing territories in your organization.

Endpoints

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"
        }
 ]
}