Add Territories

Purpose

To add new territories to your organization.

Endpoints

POST /settings/territories

Request Details

Request URL

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

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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/v5/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 (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 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

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.
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.
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": "431581000000734292"
            },
            "message": "Territory Created Successfully",
            "status": "success"
        },
        {
            "code": "SUCCESS",
            "details": {
                "id": "431581000000734310"
            },
            "message": "Territory Created Successfully",
            "status": "success"
        }
    ]
}