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 namesPossible 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

ParameterData TypeDescription
sharedTo
(optional)
StringPass the current user’s ID to know the details like the ID and the module of the records shared with that user.
view
(optional)
StringRepresents the details of the shared records that you want to retrieve. Possible values are:

Response Structure

AttributeData TypeDescription
share_related_recordsBooleanRepresents 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_throughJSON ObjectRepresents 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.
permissionStringRepresents 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.
userJSON ObjectRepresents 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:

  1. 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.

  2. Whether the record is shared alone or with related list. The records that are shared alone have higher precedence.

  3. The permissions given to the user. The order of precedence is from high to low—Full Access, Read-Write, Read-only

  4. The time at which the record was shared. The order of precedence is from oldest to latest.

Possible Errors

HTTP StatusError CodeMessageReason
401OAUTH_SCOPE_MISMATCHinvalid oauth scope to access this URLThe 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.
404INVALID_URL_PATTERNPlease check if the URL trying to access is a correct one.The URL given has syntactical errors.
403INVALID_DATAENTITY_ID_INVALIDThe record ID given in the URL is either invalid
(or)
does not belong to the module mentioned.
403INVALID_DATAScheduler is runningThe 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"
        }
    ]
}