Assign Territories to Records

Purpose

To assign territories to multiple records or a single record.

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