Remove Territories of Records

Purpose

To remove territories assigned to multiple records or a single record in your Zoho CRM organization.

Endpoints

POST /{module_api_name}/actions/remove_territories
POST /{module_api_name}/{record_ID}/actions/remove_territories

Request Details

Request URL

{api-domain}/crm/{version}/{module_api_name}/actions/remove_territories

To remove territories of a single record:
{api-domain}/crm/{version}/{module_api_name}/{record_ID}/actions/remove_territories

Supported modules

Leads, Accounts, Contacts, and Deals

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.modules.ALL
(or)
scope=ZohoCRM.modules.{module_name}.{operation_type}

Possible module names

leads, accounts, contacts, and deals

Possible operation types

ALL - Full access to the record
UPDATE - Update records in the module

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/Accounts/actions/remove_territories"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @removeterritories.json
-X POST

Request JSON Keys

idstring, mandatory if not specified in URL
Represents the unique ID of the Deal, Account, or the Contact you want to remove territories of.
TerritoriesJSON array, mandatory
Each JSON object in the array represents the unique ID of the territory you want to remove for the record. Use the Get Territories API to get the list of available territories and their respective unique IDs.

Sample Input

Copied{
    "data": [
        {
            "id": "554023000003635023", //record_id
            "Territories": [
                {
                    "id": "554023000000430409"
                },
                {
                    "id": "554023000000430451"
                }
            ]
        }
    ]
}

Response JSON Keys

codestring
Represents the response code. "SCHEDULED" indicates that a job is scheduled successfully to remove territories.
detailsJSON object
- id-string - Represents the ID of the record whose territories you want to remove.
- job_id-string - Represents the ID of the job scheduled to remove territories of the records. Use the record ID in the Get feature-specific info API for the details of the scheduled job for that record.

Possible Errors

ALREADY_SCHEDULEDHTTP 400
You are trying to remove territories again from the record(s) while a job is already scheduled.
Resolution: After scheduling the job, use the Get feature-specific info API for the status of the scheduled job for that record.
INVALID_DATAHTTP 400
The record Id given seems to be invalid
Resolution: The record ID specified in the request is incorrect. Use the Get Records API to get the list of available records and their respective unique IDs. Specify valid record ID in the request.
INVALID_DATAHTTP 400
the id given seems to be invalid
Resolution: You have specified an incorrect territory ID (or) you are trying to remove a territory that is not assigned to that record. The "details" key gives the path of the territory JSON object with the invalid ID. Use the Get Territories API to get the list of available territories and their respective unique IDs. Specify valid territory ID in the request input.
MANDATORY_NOT_FOUNDHTTP 400
One of the expected parameter is missing
Resolution: You have not specified the unique ID of the record from which the territory must be removed. Use the Get Records API to get the list of available records and their respective unique IDs. Specify valid record ID in the request input.
MANDATORY_NOT_FOUNDHTTP 400
required field not found
Resolution: You have not specified the territory ID in the input (or) passed an empty JSON array for the "Territories" key (or) you have not specified the "Territories" key in your request input. Use the Get Territories API to get the list of available territories and their respective unique IDs. Specify valid territory ID in the request input.
TERRITORY_NOT_ENABLEDHTTP 403
You are trying to remove a territory from a record in the Leads module
Resolution: You cannot directly remove territories from Leads using this API. Contact the support team to raise a request for the same.
NOT_ALLOWEDHTTP 403
You are trying to remove a territory from a record that was system-assigned. Resolution: You cannot remove system-assigned territories from records.
INVALID_DATAHTTP 207
One or more keys have invalid values in the request input. The response has multiple response states.
Resolution: Refer to request JSON keys section above and specify valid request input.
RECORD_LOCKEDHTTP 400
You cannot perform this operation as the record is locked.
Resolution: Please wait until the record is unlocked.
OAUTH_SCOPE_MISMATCHHTTP 401
invalid oauth scope to access this URL
Resolution: Client does not have ZohoCRM.modules.{module_name}.UPDATE scope. Create a new client with valid scope. Refer to scope section above.
NO_PERMISSIONHTTP 403
Permission denied to update records
Resolution: The user does not have permission to update records. Contact your system administrator.
INTERNAL_ERRORHTTP 500
Internal Server Error
Resolution: Unexpected and unhandled exception in Server. Contact support team.
INVALID_REQUEST_METHODHTTP 400
The http request method type is not a valid one
Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above.
AUTHORIZATION_FAILEDHTTP 401
User does not have sufficient privilege to update records
Resolution: The user does not have the permission to update records. Contact your system administrator.

Sample Response

Copied{
    "data": [
        {
            "code": "SCHEDULED",
            "details": {
                "job_id": "554023000003908009",
                "id": "554023000003635023"
            },
            "message": "Territory removal process scheduled successfully",
            "status": "success"
        }
    ]
}