Kaizen #49 - Share Records #API

Kaizen #49 - Share Records #API

Hello Everyone!

Welcome back to another week of Kaizen!
In this post, we will discuss Share Records via Zoho CRM API.

Record-level sharing
In Zoho CRM, users can share individual records from any module with other users in the organization. You can share records using share records API.

Pre-requisite
Users with the Administrator profile can always share records with other users in the organization. For users with other profiles, the sharing permission must be enabled.

To enable share permission,
  1. Go to Setup > Users and Control > Security Control.
  2. Select a profile to which you want to enable the permission.
  3. Enable the Share permission under Tool Permissions.
  4. Select the checkbox(es) for the corresponding modules to which you want to enable Share permission.
1. Share Records via API
Using the share records API, you can share individual records from any module with other users in the organization.
Request URL: {{api-domain}}/crm/v2/Quotes/4150868000002515001/actions/share
Request method: POST

Sample Input
{
    "share": [
        {
            "user": {
                "id": "4150868000001248015"
            },
            "share_related_records": true,
            "permission": "full_access"
        },
        {
            "user": {
                "id": "4150868000001199001"
            },
            "share_related_records": true,
            "permission": "read_only"
        }
    ]
}

Input JSON
Key
Description
user
JSON object, Mandatory
Specify the unique ID of the user in the "id" key. You can retrieve valid user IDs from Get Users API. 
share_related_records
Boolean, Optional
Represents if you want to share the record along with the related records:
true - share related records along with the record. 
false - Do not share related records. This is the default value. 
Permission
String, Optional
Represents the access permission you want to give the user for the record: 
full_access - Allow user the full access(read, edit, delete) to the record. The user with whom the record is shared can also update the owner of the record. However, the user cannot share the record with another user. This is the default value. 
read_only - Allow the user to only view the record. 
read_write - Allow the user to view and edit the record. The user with whom the record is shared cannot update the owner of the record.

Note:
  • A record can be shared with a maximum of 10 users. Through related lists, a record can be shared with a maximum of 12 users. If you exceed this limit, the system throws the SHARE_LIMIT_EXCEEDED error. 
  • You can share records from any module except the activities module and linking module. They must be shared as related records. Refer to the Input JSON section, to know how to share a record with related list. 
  • You can only share the records with users who do not already have access to it.
  • Only record owners and users with the administrator profile can share their records with other active and confirmed users in the organization.
Sample Response


2. Get Details of a Shared Record

Using the get shared record details API, you can retrieve the details of a shared record. For instance, whether the record is shared with or without the related lists, the access-permission of the record, the details of the users with whom the record is shared with, and so on. 

Request URL: {{api-domain}}/crm/v2/Quotes/4150868000002515001/actions/share
Request method: GET

Sample Response


Response JSON
Key
Description
shared_through
JSON object
Represents the module API name, module ID of the module from which the record was shared. Also, represents the unique ID of the record. 
user
JSON object
Represents the name and unique ID of the user, and ZUID of the organization to which the user belongs. 

3. Update share permissions

Using the update share permissions API, you can update the sharing permissions, revoke access to the shared record, and update access permission to the related lists of the shared record. 

Request URL: {{api-domain}}/crm/v2/Quotes/4150868000002515001/actions/share
Request method: PUT

Sample Input
{
    "share": [
        {
            "user": {
                "id": "4150868000001248015"
            },
            "share_related_records": true,
            "permission": "read_only"
        },
        {
            "user": {
                "id": "4150868000001199001"
            },
            "share_related_records": false,
            "permission": "full_access"
        }
    ]
}

Note:
  • You can choose to share the record with other users by adding the details to the JSON array. To revoke permission, remove the user's details from the JSON array.
  • Apart from adding, removing users, you can update share permissions (read_only, read_write, full_access), and permission to access related records (share_related_records) for existing shared users.
  • Ensure that you don't share the same record with more than 10 users. 
Sample Response


4. Revoke shared records
Using revoke shared records API, you can revoke access to a shared record.

Request URL: {{api-domain}}/crm/v2/Quotes/4150868000002515001/actions/share
Request method: DELETE

Sample Response


Note:
  • When you fire this API, the system revokes the record from all the shared users.
  • You can revoke share permissions only for a single record per API call. 
We hope you found this post useful. 
Write to us at support@zohocrm.com if you have any questions, or let us know in the comment section.
Cheers!