API for managing user territories in Zoho CRM. Published by Zoho in its first-party OpenAPI 3.1.0 repository github.com/zoho/crm-oas; 5 operation(s).
{
"openapi": "3.1.0",
"info": {
"title": "Users Territories",
"description": "API for managing user territories in Zoho CRM",
"version": "8"
},
"servers": [
{
"url": "https://zohoapis.{dc}/crm/{version}",
"description": "API Server URL",
"variables": {
"dc": {
"enum": [
"com",
"eu",
"in",
"cn",
"au"
],
"default": "com",
"description": "API Server URL TLD"
},
"version": {
"default": "v8",
"description": "API Version"
}
}
}
],
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.users.ALL",
"ZohoCRM.settings.territories.ALL"
]
}
],
"paths": {
"/users/{user}/territories": {
"get": {
"operationId": "getTerritoriesOfUser",
"description": "Get Territories Assigned to a User",
"summary": "Get Territories of User",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.territories.READ",
"ZohoCRM.users.READ"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/User"
}
],
"responses": {
"200": {
"description": "Successful retrieval of territories assigned to the user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerritoryGetResponse"
}
}
}
},
"204": {
"description": "No Content"
},
"400": {
"description": "Invalid User ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommonUrlErrorResponse"
}
}
}
}
}
},
"put": {
"operationId": "associateTerritoriesToUser",
"summary": "Associate Territories to User",
"description": "Associate Territories to a User",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.territories.UPDATE",
"ZohoCRM.users.UPDATE"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/User"
}
],
"requestBody": {
"content": {
"application/json": {
"schema": {
"additionalProperties": false,
"description": "Request body to associate territories to a user",
"type": "object",
"properties": {
"territories": {
"description": "List of territory IDs to associate",
"maxItems": 200,
"type": "array",
"items": {
"description": "Territory ID",
"additionalProperties": false,
"type": "object",
"properties": {
"id": {
"format": "int64",
"description": "ID of the territory",
"type": "string"
}
},
"required": [
"id"
]
}
}
},
"required": [
"territories"
]
}
}
},
"required": true
},
"responses": {
"200": {
"description": "200 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"400": {
"description": "400 response",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommonErrorResponse"
}
}
}
},
"403": {
"description": "Logged in users cannot update their own territories.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommonUrlErrorResponse"
}
}
}
}
}
},
"delete": {
"summary": "Remove Territories from User",
"description": "Remove Territories from a User",
"operationId": "removeTerritoriesfromUser",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.territories.DELETE",
"ZohoCRM.users.DELETE"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/User"
},
{
"$ref": "#/components/parameters/Ids"
}
],
"responses": {
"200": {
"description": "Successful removal of territories from the user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"400": {
"description": "Invalid territory IDs",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommonErrorResponse"
}
}
}
}
}
}
},
"/users/{user}/territories/{territory}": {
"get": {
"summary": "Get specific Territory of User",
"description": "Get specific territory of a user",
"operationId": "getSpecificTerritoryOfUser",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.territories.READ",
"ZohoCRM.users.READ"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/User"
},
{
"$ref": "#/components/parameters/Territory"
}
],
"responses": {
"200": {
"description": "Get specific territory of a user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/TerritoryGetResponse"
}
}
}
},
"204": {
"description": "No Content"
},
"400": {
"description": "Invalid User ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommonUrlErrorResponse"
}
}
}
}
}
},
"delete": {
"description": "Remove Territory from a User",
"summary": "Remove Territory from User",
"operationId": "removeSpecificTerritoriesfromUser",
"security": [
{
"iam-oauth2-schema": [
"ZohoCRM.settings.territories.DELETE",
"ZohoCRM.users.DELETE"
]
}
],
"parameters": [
{
"$ref": "#/components/parameters/User"
},
{
"$ref": "#/components/parameters/Territory"
}
],
"responses": {
"200": {
"description": "Successful removal of territories from the user",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/SuccessResponse"
}
}
}
},
"400": {
"description": "Invalid territory ID",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/CommonUrlErrorResponse"
}
}
}
}
}
}
}
},
"components": {
"parameters": {
"User": {
"description": "The ID of the user",
"name": "user",
"in": "path",
"required": true,
"schema": {
"format": "int64",
"type": "string"
}
},
"Territory": {
"description": "The ID of the territory",
"name": "territory",
"in": "path",
"required": true,
"schema": {
"format": "int64",
"type": "string"
}
},
"Ids": {
"description": "Comma-separated IDs (each ID is an int64)",
"name": "ids",
"in": "query",
"required": true,
"schema": {
"type": "string",
"description": "Comma-separated IDs (digits only, separated by commas)",
"pattern": "^[0-9]+(,[0-9]+)*$",
"maxLength": 2000
}
}
},
"schemas": {
"CommonUrlErrorResponse": {
"type": "object",
"additionalProperties": false,
"description": "Error response for INVALID_DATA that includes a resource_path_index in details",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA",
"NOT_ALLOWED"
]
},
"details": {
"type": "object",
"description": "Error details containing resource path index",
"additionalProperties": false,
"properties": {
"resource_path_index": {
"type": "integer",
"description": "Index of the resource path",
"format": "int32"
}
}
},
"message": {
"type": "string",
"description": "Human readable error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Status of the error",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"status"
]
},
"CommonErrorResponse": {
"type": "object",
"additionalProperties": false,
"description": "Response containing an array of per-territory error items",
"properties": {
"territories": {
"type": "array",
"description": "List of per-territory error items",
"minItems": 0,
"maxItems": 200,
"uniqueItems": true,
"items": {
"type": "object",
"additionalProperties": false,
"description": "Per-territory error object for territory-specific validation failures",
"properties": {
"code": {
"type": "string",
"description": "Error code",
"enum": [
"INVALID_DATA",
"DUPLICATE_DATA",
"PERMISSION_DENIED"
]
},
"details": {
"type": "object",
"description": "Error details for the territory",
"additionalProperties": false,
"properties": {
"api_name": {
"type": "string",
"description": "The API field name related to the error",
"maxLength": 255
},
"json_path": {
"type": "string",
"description": "JSON path that points to the invalid value",
"maxLength": 1000
}
}
},
"message": {
"type": "string",
"description": "Human-readable error message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Status of the error",
"enum": [
"error"
]
}
},
"required": [
"code",
"details",
"status"
]
}
}
},
"required": [
"territories"
]
},
"TerritoryGetResponse": {
"additionalProperties": false,
"description": "Response schema for getting territories of a user",
"type": "object",
"properties": {
"territories": {
"type": "array",
"description": "List of territories assigned to the user",
"minItems": 0,
"maxItems": 200,
"uniqueItems": true,
"items": {
"type": "object",
"description": "Territory details",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"description": "Territory ID",
"format": "int64"
},
"Manager": {
"type": "object",
"description": "Territory manager details",
"additionalProperties": false,
"properties": {
"Name": {
"type": "string",
"description": "Manager name",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Manager ID",
"format": "int64"
}
}
},
"Reporting_To": {
"type": "object",
"description": "Reporting manager details",
"additionalProperties": false,
"properties": {
"Name": {
"type": "string",
"description": "Reporting manager name",
"maxLength": 255
},
"id": {
"type": "string",
"description": "Reporting manager ID",
"format": "int64"
}
},
"required": [
"Name",
"id"
]
},
"Name": {
"type": "string",
"description": "Territory name",
"maxLength": 255
}
},
"required": [
"id",
"Manager",
"Reporting_To",
"Name"
]
}
},
"info": {
"type": "object",
"description": "Pagination information",
"additionalProperties": false,
"properties": {
"count": {
"type": "integer",
"description": "Number of records returned",
"format": "int32"
},
"page": {
"type": "integer",
"description": "Current page number",
"format": "int32"
},
"per_page": {
"type": "integer",
"description": "Records per page",
"format": "int32"
},
"more_records": {
"type": "boolean",
"description": "Whether more records exist"
}
},
"required": [
"count",
"page",
"per_page",
"more_records"
]
}
},
"required": [
"territories",
"info"
]
},
"SuccessResponse": {
"type": "object",
"additionalProperties": false,
"description": "Response for successful association of territories to a user",
"properties": {
"territories": {
"type": "array",
"description": "List of per-territory result items",
"minItems": 0,
"maxItems": 200,
"uniqueItems": true,
"items": {
"type": "object",
"additionalProperties": false,
"description": "Per-territory result item",
"properties": {
"code": {
"type": "string",
"description": "Result code",
"enum": [
"SUCCESS"
]
},
"details": {
"type": "object",
"description": "Details for the result item",
"additionalProperties": false,
"properties": {
"id": {
"type": "string",
"format": "int64",
"description": "ID of the territory"
}
},
"required": [
"id"
]
},
"message": {
"type": "string",
"description": "Human-readable message",
"maxLength": 1000
},
"status": {
"type": "string",
"description": "Status of the result",
"enum": [
"success"
]
}
},
"required": [
"code",
"details",
"message",
"status"
]
}
}
},
"required": [
"territories"
]
}
},
"securitySchemes": {
"iam-oauth2-schema": {
"type": "oauth2",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://accounts.zoho.com/oauth/v2/auth",
"tokenUrl": "https://accounts.zoho.com/oauth/v2/token",
"refreshUrl": "https://accounts.zoho.com/oauth/v2/token",
"scopes": {
"ZohoCRM.users.ALL": "Full access to user resources (read/write) within Zoho CRM",
"ZohoCRM.settings.territories.ALL": "Full access to territories settings (read/write) within Zoho CRM",
"ZohoCRM.users.READ": "Read-only access to user resources within Zoho CRM",
"ZohoCRM.settings.territories.READ": "Read-only access to territories settings within Zoho CRM",
"ZohoCRM.users.UPDATE": "Update access to user resources within Zoho CRM",
"ZohoCRM.settings.territories.UPDATE": "Update access to territories settings within Zoho CRM",
"ZohoCRM.users.DELETE": "Delete access to user resources within Zoho CRM",
"ZohoCRM.settings.territories.DELETE": "Delete access to territories settings within Zoho CRM"
}
}
}
}
}
}
}