Remove Territories of Records

Purpose

To remove territories assigned to multiple records or a single record.

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

Note

When you have chosen to offload parent territory, a job is scheduled in the background. Go here to see the response of the scheduled job.
If you want to enable this feature, contact support at support@zohocrm.com.

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/v5/Deals/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 from.
TerritoriesJSON array, mandatory
Each JSON object in the array represents the unique ID of the territory you want to remove from the record. Use the Get Territories API to get the list of available territories and their respective unique IDs.

Sample Input

Copied{
  "data": [
    {
      "id": "4150868000004522032",
      "Territories": [
        {
          "id": "4150868000000236307"
        },
        {
          "id": "4150868000000264087"
        }
      ]
    },
    {
      "id": "4150868000004318009",
      "Territories": [
        {
          "id": "4150868000000236307"
        },
        {
          "id": "4150868000000264087"
        }
      ]
    }
  ]
}

Possible Errors

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 400
User does not have sufficient privilege to update records
Resolution: The user does not have the permission to update records. Contact your system administrator.
INVALID_DATAHTTP 400
The record Id given seems to be invalid
Resolution: The record ID specified in the request input 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 input.
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_ENABLE DHTTP 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.

Sample Response

Copied{
  "data": [
    {
      "code": "SUCCESS",
      "details": {
        "id": "4150868000004318009"
      },
      "message": "the terriroies data removed successfully",
      "status": "success"
    }
  ]
}

Response JSON when parent territory is offloaded

codestring
Represents the response code.
detailsJSON object
- id-string - Represents the ID of the record you want to remove from a territory.
- 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.

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "2345678234534545", //record id
                "job_id": "482367546723546372"
            },
            "message": "Territory removal process scheduled successfully",
            "status": "success"
        }
    ]
}