Mass Change Owner

Purpose

To bulk update the ownership of records in a specific custom view or territory in a module in Zoho CRM.

Endpoints

  • POST /{module_API_name}/actions/mass_change_owner

Request Details

Request URL

{api-domain}/crm/{version}/{module_API_name}/actions/mass_change_owner

Supported modules

Leads, Accounts, Contacts, Deals, Campaigns, Tasks, Cases, Meetings, Calls, Solutions, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, and Custom

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.change_owner.CREATE

Note

  • You cannot change the owner of the related records.
  • You can change the owner of up to 50,000 records in a custom view.
  • This API schedules a job and gives you a job ID to get the status of the API.
  • Job statuses are retrievable for up to 60 days.
  • The Mass Change Owner API is supported in both the Enterprise and Ultimate editions.

Sample Request

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

Request JSON

  • cvidstring, mandatory

    The unique ID of the custom view of whose records you want to change the owner. Use the Custom View Metadata API to get the ID of the custom view. Note that when you want to change the owner of the records in a custom view, this API schedules a job and returns a job ID. Use this ID with the Mass Change Owner Status API to track the job status.

  • ownerJSON object, mandatory

    The unique ID of the new owner to assign the records to. Use the Get Users API to get the ID of the user.

  • territoryJSON object, mandatory when you want to change the owner of the records in a territory

    The unique ID of the territory whose records are to be reassigned to the new owner. Use the Get Territories API to get the ID of the territory.

  • criteriaJSON object, optional

    Apply specific conditions to filter the records whose ownership will be changed.

    • fieldJSON object, optional

      The field to which the condition applies. Provide its API name or unique ID. Retrieve field details using the Field Metadata API.

    • comparatorstring, mandatory (it is mandatory when you use criteria)

      Specifies the comparison operator. 

    • valuestring, mandatory (it is mandatory when you use criteria)

      The specific value the field must match for the condition to be applied.

Sample Input

Copied{
    "cvid" : "2423488000000091545",
    "owner":{
        "id" : "2423488000000483001"
    },
    "territory": {
        "id": "2423488000000780003",
        "include_child": true
    },
    "criteria" : {
        "field" : {
            "api_name" : "Stage",
            "id" : "2423488000000000525"
        },
        "comparator" : "equal",
        "value": "Qualification"
    }
}

In the sample request, the criteria filter records in the Deals module where the Stage field is set to Qualification. These filtered records, within the specified territory and custom view, are then reassigned to a new owner.

Response JSON

  • codestring

    Represents the outcome of the request.

  • detailsJSON object

    Contains the unique identifier for the scheduled job. This ID can be used with the Mass Change Owner Status API to monitor the job's progress and outcome.

  • messagestring

    A brief message confirming the status of the request.

  • statusstring

    Indicates the status of the request.

Possible Errors

  • INVALID_REQUEST_METHODHTTP 400

    The request method is incorrect.
    Resolution: Use the HTTP PUT method to make this API call. Any other request method will result in this error.

  • INVALID_DATAHTTP 400

    Reasons:

    • The CVID is invalid.
    • The territory's ID is invalid.
    • The user's ID is invalid.
    • The user you are trying to assign the records to is deleted from your org.
    • The user you are trying to assign the records to is inactive.

    Resolutions:

    • Provide valid IDs of the user, CVID, and the territory.
  • MANDATORY_NOT_FOUNDHTTP 400

    You have not specified either the CVID, the owner's ID, or both.
    Resolution: CVID and Owner's ID is mandatory in the input.

  • RECORD_LIMIT_EXCEEDEDHTTP 400

    The custom view has more than 50,000 records.
    Resolution: You can only change the owner of up to 50,000 records in a custom view through this API.

  • NO_PERMISSIONHTTP 403

    Reasons:

    • You do not have permission to the module.
    • You do not have permission to change the owner.
    • You do not have permission to view the records in that custom view.

    Resolution: Contact your system administrator to obtain sufficient permissions.

  • INVALID_URL_PATTERNHTTP 404

    The request URL is incorrect.
    Resolution: Specify a valid request URL. Refer to the request URL section at the beginning of this page for more details.

  • INTERNAL_ERRORHTTP 500

    Unexpected and unhandled exception in the server. 
    Resolution: Contact the support team at support@zohocrm.com.

Sample Response

Copied{
    "data": [
        {
            "code": "SUCCESS",
            "details": {
                "job_id": "3652397000009026002"
            },
            "message": "change owner is successfully scheduled",
            "status": "success"
        }
    ]
}