Transfer Records and Delete Users

Purpose

To delete user(s) from CRM and transfer the records to a new user. You can replace the user at the following places:

Ownership: You can transfer all open records of the old user to the new user.
Assignment: You can replace the old user with new at places like assignment rules, escalation rules, field updates, automation actions etc.
Configuration/criteria: You can replace the user where the old user is used in criteria for custom views, automation, reports etc.

Endpoints

POST /users/{user_id}/actions/transfer_and_delete

Request Details

Request URL

{api-domain}/crm/{version}/users/actions/transfer_and_delete
To delete a specific user: {api-domain}/crm/{version}/users/{user_id}/actions/transfer_and_delete

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

scope=ZohoCRM.users.ALL
(or)
scope=ZohoCRM.users.DELETE

Sample Request

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

Input JSON

When you delete more than one user through this API, a scheduler schedules a job and returns the job ID in the response. Use the Status API to check the status of the job.

idstring, mandatory if not given in the request URL and to delete multiple users
The unique ID of the user that you want to delete and transfer the open records to another user. Use the Get Users API to get the ID of the user.
transferJSON object, mandatory
The details of the new user you want to transfer the records of the old user to.
- id,string, mandatory - The record ID of the user you want to transfer the records of the old user to. Use the Get Users API to get the ID of the user.
- records,Boolean, mandatory - true indicates that you want to transfer the open records to the new user.
- assignment,Boolean, mandatory - true indicates that you want to replace the user at places such as assignment rules, escalation rules, field updates, automation actions etc.
- criteria,Boolean, mandatory - true indicates that you want to replace the user at places where the old user is used in criteria for custom views, automation, reports etc.
move_subordinateJSON object, mandatory if "transfer" is not given
The details of the new user you want to transfer the subordinates of the old user to.
- id,string, mandatory - The record ID of the user you want to transfer the subordinates of the old user to. Use the Get Users API to get the ID of the user.

Sample Input

Copied{
    "transfer_and_delete": [
        {
            "id": "3652397000001464001",
            "transfer": {
                "id": "3652397000000186017",
                "records": true,
                "assignment": true,
                "criteria": true
            },
            "move_subordinate": {
                "id": "3652397000000186017"
            }
        }
    ]
}

Possible Errors

MANDATORY_NOT_FOUNDHTTP 400
You have not included the ID of the user you want to delete.
Resolution: You must include the ID of the user that you want to delete either in the request URL or in the input body. Use the Get Users API to get the ID of the user.
EXPECTED_FIELD_MISSINGHTTP 400
You have neither specified "transfer" nor "move_subordinate" in the input.
Resolution: Specify either "transfer" or "move_subordinate" in the input.
INVALID_DATAHTTP 400
You have specified an incorrect user ID either in the URL or in the body.
Resolution: Specify the right user ID.
INVALID_DATAHTTP 400
The user you are trying to delete or the user you want to transfer the records to is not a CRM user.
Resolution: You can only delete CRM users and transfer the records to a CRM user. Use the Get Users API to get the list of users in your org. Refer to the "details" key in the response.
INVALID_DATAHTTP 400
The user you are trying to delete or the user you want to transfer the records to is already deleted.
Resolution: You cannot delete or transfer records to already deleted users.
INVALID_DATAHTTP 400
The user's ID that you are trying to transfer the records to is invalid.
Resolution: Provide a valid user ID.
INVALID_DATAHTTP 400
The user you are trying to transfer the subordinates to is inactive.
Resolution: You can move the subordinates to only active users.
INVALID_DATAHTTP 400
You have specified the user ID in the URL but the request body has more than one JSON object.
Resolution: If you specify the user ID in the URL, you can delete only that user, and the request body must contain details of only that user.
INVALID_DATAHTTP 400
You are trying to delete more than one user through this API.
Resolution: You can use this API to delete only one user and transfer records to another user.
NOT_ALLOWEDHTTP 400
The user you are trying to transfer the subordinates to is a subordinate user.
Resolution: You cannot move the subordinates to another subordinate user.
NOT_ALLOWEDHTTP 400
The user you are trying to delete is the super admin of the org.
Resolution: You cannot delete the super admin of the org.
NO_PERMISSIONHTTP 403
You are not the super admin of your org and cannot access this API.
Resolution: Only super admin of the org can delete users and transfer the records.

Sample Response

Copied{
    "transfer_and_delete": [
        {
            "code": "SUCCESS",
            "details": {
                "jobId": "3652397000012622009",
                "id": "3652397000001464001"
            },
            "message": "user is deleted successfully",
            "status": "success"
        }
    ]
}