Share Records API

In Zoho CRM, we have different levels of data sharing. One of them is record-level data sharing, where the users can share individual records with other users in the organization. The records can be shared with or without the related lists.

Get Shared Record Details

Purpose

To get the details of a shared record.

Request URL

https://www.zohoapis.com/crm/v2/{module_api_name}/{record_id}/actions/share

Request Method

GET

Scope

scope=ZohoCRM.share.{module_name}.{operation_type}

Possible module names	Possible operation types
leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, and custom.	ALL - Full access to the record READ - Get shared record's details

Parameters

Parameter

Data Type

Description

sharedTo
(optional)

String

Pass the current user’s ID to know the details like the ID and the module of the records shared with that user.

view
(optional)

String

Represents the details of the shared records that you want to retrieve. Possible values are:

summaryShow properties
manageShow properties

Response Structure for 'summary' Parameter

If you use the 'summary' parameter, you will get the following additional details.

Attributes	Data Type	Description
entity_name	String	Represents the entity name of the record shared. It is a part of "shared_through" JSON object. The entity name differs based on module: Full Name - Leads and Contacts Name - Accounts, Deals, Products, Campaigns, Vendors, Price Books Subject - Quotes, Invoices, Purchase Orders, Sales Orders, Cases, and Solutions.
shared_time	Date/Time in ISO 8601 format	Represents the date and time at which the record was shared.
shared_by	JSON Object	Represents the details of the user who is shared the record. Each "shared_by" object has the Full Name, ID, and ZUID of the user.

Response Structure for 'manage' Parameter

If you use the 'manage' parameter, you will get the following additional details.

Attributes	Data Type	Description
shareable_user	JSON Array	Represents the list of other users that the current user can share this record with. Each "shareable_user" object has a Full Name, ID, and ZUID of the user.

Response Structure

Attribute	Data Type	Description
share_related_records	Boolean	Represents if the record is shared with or without related records. true - The record is shared with related records. false - The record is shared without related records.
shared_through	JSON Object	Represents the details of the module from which the record has been shared. Every "module" object represents the API name and ID of the module. It also represents the unique ID of the shared record.
permission	String	Represents the access permission given to the user for that record. full_access - Allow the user full access to the record. read_only - Allow the user to view the record. read_write - Allow the user to view and edit the record.
user	JSON Object	Represents the users details with whom the record is shared. Each user JSON object represents the following: full_name - The full name (First_Name + Last_Name) of the user. ID - The user's record ID. ZUID - The unique ID of the user.

Note

The result is sorted based on the following criteria in the order mentioned below:

The order in which the records are shared. For instance, if a record is shared to user A and then to user B, in the result, user B's details will be displayed first.
Whether the record is shared alone or with related list. The records that are shared alone have higher precedence.
The permissions given to the user. The order of precedence is from high to low—Full Access, Read-Write, Read-only
The time at which the record was shared. The order of precedence is from oldest to latest.

Possible Errors

HTTP Status	Error Code	Message	Reason
401	OAUTH_SCOPE_MISMATCH	invalid oauth scope to access this URL	The client does not have the scope to ZohoCRM.share.{module_name}.READ (or) The module name given in the URL is either Events, Calls, Tasks or any Linking module. (or) The module name given in the URL is invalid.
404	INVALID_URL_PATTERN	Please check if the URL trying to access is a correct one.	The URL given has syntactical errors.
403	INVALID_DATA	ENTITY_ID_INVALID	The record ID given in the URL is either invalid (or) does not belong to the module mentioned.
403	INVALID_DATA	Scheduler is running	The record is either being shared or revoked currently.

Sample Request (Without any parameter)

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/4150868000001191072/actions/share"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "share": [
        {
            "share_related_records": false,
            "shared_through": {
                "module": {
                    "name": "Contacts",
                    "id": "4150868000000002179"
                },
                "id": "4150868000001191072"
            },
            "permission": "full_access",
            "user": {
                "full_name": "Thomas Mill",
                "id": "4150868000001174048",
                "zuid": "705833797"
            }
        },
        {
            "share_related_records": false,
            "shared_through": {
                "module": {
                    "name": "Contacts",
                    "id": "4150868000000002179"
                },
                "id": "4150868000001191072"
            },
            "permission": "full_access",
            "user": {
                "full_name": "Samuel",
                "id": "4150868000001199001",
                "zuid": "705903469"
            }
        }
    ]
}

Sample Request: With sharedTo parameter

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/4150868000001191072/actions/share?view=summary&sharedTo=4150868000001199001"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "share": [
        {
            "share_related_records": false,
            "shared_through": {
                "entity_name": "Amanda Carr",
                "module": {
                    "name": "Contacts",
                    "id": "4150868000000002179"
                },
                "id": "4150868000001085001"
            },
            "shared_time": "2020-01-13T16:41:03+05:30",
            "permission": "full_access",
            "shared_by": {
                "full_name": "Patricia Boyle",
                "id": "4150868000000225013",
                "zuid": "694579958"
            }
        }
    ]
}

Sample Request: With summary parameter

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/4150868000001191072/actions/share?view=summary"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "share": [
        {
            "share_related_records": false,
            "shared_through": {
                "entity_name": "John",
                "module": {
                    "name": "Contacts",
                    "id": "4150868000000002179"
                },
                "id": "4150868000001191072"
            },
            "shared_time": "2020-01-13T12:55:33+05:30",
            "permission": "full_access",
            "shared_by": {
                "full_name": "Patricia Boyle",
                "id": "4150868000000225013",
                "zuid": "694579958"
            },
            "user": {
                "full_name": "Thomas Mill",
                "id": "4150868000001174048",
                "zuid": "705833797"
            }
        },
        {
            "share_related_records": false,
            "shared_through": {
                "entity_name": "John",
                "module": {
                    "name": "Contacts",
                    "id": "4150868000000002179"
                },
                "id": "4150868000001191072"
            },
            "shared_time": "2020-01-13T12:55:33+05:30",
            "permission": "full_access",
            "shared_by": {
                "full_name": "Patricia Boyle",
                "id": "4150868000000225013",
                "zuid": "694579958"
            },
            "user": {
                "full_name": "Samuel",
                "id": "4150868000001199001",
                "zuid": "705903469"
            }
        }
    ]
}

Sample Request: With manage parameter

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/4150868000001191072/actions/share?view=manage"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"

Sample Response

Copied{
    "share": [
        {
            "share_related_records": false,
            "permission": "read_only",
            "user": {
                "full_name": "Thomas Mill",
                "id": "4150868000001174048",
                "zuid": "705833797"
            }
        }
    ],
    "shareable_user": [
        {
            "full_name": "Samuel",
            "id": "4150868000001199001",
            "zuid": "705903469"
        }
    ]
}