Remove Territories of Records

Purpose

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

Endpoints

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/v2.1/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.

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"
        }
    ]
}