Assign Territories to Records

Purpose

To assign territories to multiple records or a single record.

Endpoints

POST /{module_api_name}/actions/assign_territories

POST /{module_api_name}/{record_id}/actions/assign_territories

Request Details

Request URL

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

To assign territories to a single record:
{api-domain}/crm/{version}/{module_api_name}/{record_id}/actions/assign_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/v4/Accounts/actions/assign_territories"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @assignterritories.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 assign territories to.
TerritoriesJSON array, mandatory
Each JSON object in the array represents the unique ID of the territory you want to assign to the record. Use the Get Territories API to get the list of available territories and their respective unique IDs.

Note

You can assign only one territory to a deal.
You can assign a maximum of 10 territories to a lead, contact, or an account.

Sample Input

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

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 create records
Resolution: The user does not have permission to update variables. 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.
RECORD_LOCKEDHTTP 400
You cannot perform this operation as the record is locked.
Resolution: Please wait until the record is unlocked.
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.
LIMIT_EXCEEDEDHTTP 400
Maximum limit of territories for that record exceeds
Resolution: You can only assign a maximum of ten territories to a contact and an account, and one territory to a deal.
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) the territory you want to assign is deleted. 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 for which the territory must be assigned to. 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.
DUPLICATE_DATAHTTP 400
Given Territory id already exists for that record
Resolution: You can assign a territory to a record only once.
ALREADY_USEDHTTP 400
duplicate territory id found
Resolution: Use each territory ID only once in the input for a record.
TERRITORY_NOT_ENABLEDHTTP 403
You are trying to assign a territory to a record in the Leads module (or) the territory feature is not enabled.
Resolution: You cannot directly assign territories to Leads using this API; contact the support team to raise a request for the same. Contact your administrator to enable territory for the module whose records you want to assign a territory to.
INVALID_DATAHTTP 400
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": "4150868000004522032"
      },
      "message": "the territories data updated 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 to which you want to assign the territory.
- job_id-string - Represents the ID of the job scheduled to assign territories to 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 assignment process scheduled successfully",
            "status": "success"
        }
    ]
}