Add Territories

Purpose

To add new territories to your Zoho CRM organization.

Endpoints

POST /settings/territories

Request Details

Request URL

{api-domain}/crm/{version}/settings/territories

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.territories.{operation_type}

Possible operation types

ALL - Full access to territories
CREATE - To create territories

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/territories"
-X POST
-d "@addterritories.json"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

In the request, "@addterritories.json" contains the sample input data.

Input JSON

name string, mandatory
Represents the name of the territory.
reporting_to JSON Object, mandatory
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 (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 organization depends upon the version of CRM
Maximum number of territories that can be added in one API call is 10

Sample Input

Copied{
  "territories": [
    {
      "name": "Territory1000",
      "reporting_to": {
        "id": "431581000000272796"
      },
      "manager": {
        "id": "431581000000258001"
      },
      "permission_type": "read_only",
      "description": null,
      "account_rule_criteria": {
        "comparator": "greater_than",
        "field": {
          "api_name": "Annual_Revenue",
          "id": "431581000000000625"
        },
        "value": "1001"
      },
      "lead_rule_criteria": {
        "comparator": "greater_than",
        "field": {
          "api_name": "Annual_Revenue",
          "id": "431581000000000893"
        },
        "value": "1000"
      },
      "deal_rule_criteria": {
        "comparator": "greater_than",
        "field": {
          "api_name": "Amount",
          "id": "431581000000000799"
        },
        "value": "100000"
      }
    },
    {
      "name": "Territory1001",
      "reporting_to": {
        "id": "431581000000272796"
      },
      "manager": {
        "id": "431581000000258001"
      },
      "permission_type": "read_only",
      "account_rule_criteria": {
        "comparator": "greater_than",
        "field": {
          "api_name": "Annual_Revenue",
          "id": "431581000000000625"
        },
        "value": "10001"
      },
      "lead_rule_criteria": {
        "comparator": "greater_than",
        "field": {
          "api_name": "Annual_Revenue",
          "id": "431581000000000893"
        },
        "value": "10000"
      },
      "deal_rule_criteria": {
        "comparator": "greater_than",
        "field": {
          "api_name": "Amount",
          "id": "431581000000000799"
        },
        "value": "1000000"
      }
    }
  ]
}

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.
NOT_ALLOWEDHTTP 400
- Inactive User
- Deleted User
- Invalid User
Resolution: Give a valid user id
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.
FEATURE_NOT_ENABLEDHTTP 403
Territory Management is not enabled
Resolution: Try again after enabling territory management feature.
PERMISSION_DENIEDHTTP 400
User does't have a permission to choose that territory as a Parent Id
Resolution: The user does not have permission to add that particular territory as a parent territory. 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.
FEATURE_NOT_SUPPORTEDHTTP 403
Territory feature is not supported for standard and professional editions
Resolution: Contact your administrator.
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": "431581000000734292"
            },
            "message": "Territory Created Successfully",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "431581000000734310"
            },
            "message": "Territory Created Successfully",
            "status": "success"
        }
    ]
}