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.

Purpose

To get the details of a shared record.

Request Details

Request URL

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

Supported modules

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

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

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

Possible module names

leads, accounts, contacts, deals, campaigns, cases, solutions, products, vendors, pricebooks, quotes, salesorders, purchaseorders, invoices, and custom.

Possible operation types

ALL - Full access to the record
READ - Get shared record's details

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v2/Contacts/4150868000001191072/actions/share"
-X GET
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
3.0.08.0
CopiedString moduleAPIName = "Leads";
Long recordId = 3477061000005177002L;

//Get instance of ShareRecordsOperations Class that takes recordId and moduleAPIName as parameter
ShareRecordsOperations shareRecordsOperations = new ShareRecordsOperations(recordId, moduleAPIName);

//Get instance of ParameterMap Class
ParameterMap paramInstance = new ParameterMap();

paramInstance.add(GetSharedRecordDetailsParam.VIEW, "summary");

//paramInstance.add(GetSharedRecordDetailsParam.SHAREDTO, 3477061000005791024L);

//Call getSharedRecordDetails method that takes paramInstance as parameter
APIResponse < ResponseHandler > response = shareRecordsOperations.getSharedRecordDetails(paramInstance);
Copiedimport javax.net.ssl.SSLContext;
import org.apache.http.HttpEntity;
import org.apache.http.HttpResponse;
import org.apache.http.client.methods.HttpGet;
import org.apache.http.client.methods.HttpUriRequest;
import org.apache.http.client.utils.URIBuilder;
import org.apache.http.conn.ssl.NoopHostnameVerifier;
import org.apache.http.conn.ssl.SSLConnectionSocketFactory;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClientBuilder;
import org.apache.http.util.EntityUtils;
public class ShareRecordsAPI 
{
	public static void main(String[] args) 
	{
		try
		{
			HttpClientBuilder httpClientBuilder = HttpClientBuilder.create();
			SSLContext sslContext = SSLContext.getDefault();
			SSLConnectionSocketFactory sslConnectionSocketFactory = new SSLConnectionSocketFactory(sslContext, NoopHostnameVerifier.INSTANCE);
			CloseableHttpClient httpclient = httpClientBuilder.setSSLSocketFactory(sslConnectionSocketFactory).build();
			URIBuilder uriBuilder = new URIBuilder("https://www.zohoapis.com/crm/v2/Leads/34770615623115/actions/share");
			uriBuilder.addParameter("view", "summary");
			uriBuilder.addParameter("sharedTo", "34770610173021");
			HttpUriRequest requestObj = new HttpGet(uriBuilder.build());
			requestObj.addHeader("Authorization", "Zoho-oauthtoken 1000.xxxxxxx.xxxxxxx");
			HttpResponse response = httpclient.execute(requestObj);
			HttpEntity responseEntity = response.getEntity();
			System.out.println("HTTP Status Code : " + response.getStatusLine().getStatusCode());
			if(responseEntity != null)
			{
				Object responseObject = EntityUtils.toString(responseEntity);
				String responseString = responseObject.toString();
				System.out.println(responseString);
			}
		}
		catch(Exception ex)
		{
			ex.printStackTrace();
		}
	}
}
3.0.07.x
Copied//Get instance of ShareRecordsOperations Class that takes moduleAPIName and recordId as parameter
$shareRecordsOperations = new ShareRecordsOperations( $recordId,$moduleAPIName);
//Get instance of ParameterMap Class
$paramInstance = new ParameterMap();
$paramInstance->add(GetSharedRecordDetailsParam::view(), "summary");
// $paramInstance->add(GetSharedRecordDetailsParam::sharedTo(), "3477061000005791024");
//Call getSharedRecordDetails method that takes paramInstance as parameter
$response = $shareRecordsOperations->getSharedRecordDetails($paramInstance);
Copied<?php
class GetSharedRecords{
    
    public function execute(){
        $curl_pointer = curl_init();
        
        $curl_options = array();
        $url = "https://www.zohoapis.com/crm/v2/Leads/3477061623115/actions/share?";
        $parameters = array();
        $parameters["view"]="summary";
        $parameters["sharedTo"]="3477061173021";
        
        foreach ($parameters as $key=>$value){
            $url =$url.$key."=".$value."&";
        }
        $curl_options[CURLOPT_URL] = $url;
        $curl_options[CURLOPT_RETURNTRANSFER] = true;
        $curl_options[CURLOPT_HEADER] = 1;
        $curl_options[CURLOPT_CUSTOMREQUEST] = "GET";
        $headersArray = array();
        $headersArray[] = "Authorization". ":" . "Zoho-oauthtoken " ."1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf";
        $curl_options[CURLOPT_HTTPHEADER]=$headersArray;
        
        curl_setopt_array($curl_pointer, $curl_options);
        
        $result = curl_exec($curl_pointer);
        $responseInfo = curl_getinfo($curl_pointer);
        curl_close($curl_pointer);
        list ($headers, $content) = explode("\r\n\r\n", $result, 2);
        if(strpos($headers," 100 Continue")!==false){
            list( $headers, $content) = explode( "\r\n\r\n", $content , 2);
        }
        $headerArray = (explode("\r\n", $headers, 50));
        $headerMap = array();
        foreach ($headerArray as $key) {
            if (strpos($key, ":") != false) {
                $firstHalf = substr($key, 0, strpos($key, ":"));
                $secondHalf = substr($key, strpos($key, ":") + 1);
                $headerMap[$firstHalf] = trim($secondHalf);
            }
        }
        $jsonResponse = json_decode($content, true);
        if ($jsonResponse == null && $responseInfo['http_code'] != 204) {
            list ($headers, $content) = explode("\r\n\r\n", $content, 2);
            $jsonResponse = json_decode($content, true);
        }
        var_dump($headerMap);
        var_dump($jsonResponse);
        var_dump($responseInfo['http_code']);
        
    }
    
}
(new GetSharedRecords())->execute();
3.0.08.x
Copied//Get instance of ShareRecordsOperations Class that takes recordId and moduleAPIName as parameter
ShareRecordsOperations shareRecordsOperations = new ShareRecordsOperations(recordId, moduleAPIName);
//Get instance of ParameterMap Class
ParameterMap paramInstance = new ParameterMap();
paramInstance.Add(GetSharedRecordDetailsParam.VIEW, "summary");
//paramInstance.Add(GetSharedRecordDetailsParam.SHAREDTO, 3477061000005791024);
//Call GetSharedRecordDetails method that takes paramInstance as parameter
APIResponse<ResponseHandler> response = shareRecordsOperations.GetSharedRecordDetails(paramInstance);
Copiedusing System;
using System.IO;
using System.Net;
namespace Com.Zoho.Crm.API.Sample.RestAPI.ShareRecords
{
    public class ShareRecordsAPI
    {
        public static void ShareRecords()
        {
            HttpWebRequest request = (HttpWebRequest)WebRequest.Create("https://www.zohoapis.com/crm/v2/Leads/34770617753001/actions/share?view=summary&sharedTo=347706100173021");
            request.Method = "GET";
            request.Headers["Authorization"] = "Zoho-oauthtoken 1000.abfeXXXXXXXXXXX2asw.XXXXXXXXXXXXXXXXXXsdc2";
            request.KeepAlive = true;
            HttpWebResponse response;
            try
            {
                response = (HttpWebResponse)request.GetResponse();
            }
            catch (WebException e)
            {
                if (e.Response == null) { throw; }
                response = (HttpWebResponse)e.Response;
            }
            HttpWebResponse responseEntity = response;
            Console.WriteLine("HTTP Status Code : " + (int)response.StatusCode);
            string responsestring = new StreamReader(responseEntity.GetResponseStream()).ReadToEnd();
            responseEntity.Close();
            Console.WriteLine(responsestring);
        }
    }
}
3.0.03.x.x
Copied# Get instance of ShareRecordsOperations Class that takes module_api_name and record_id as parameter
shared_records_operations = ShareRecordsOperations(record_id, module_api_name)
# Get instance of ParameterMap Class
param_instance = ParameterMap()
# Possible parameters of Get Shared Record Details operation
# Allowed values - summary, manage
param_instance.add(GetSharedRecordDetailsParam.view, 'summary')
# param_instance.add(GetSharedRecordDetailsParam.sharedto, 3409643000000302031)
# Call get_shared_record_details method that takes ParameterMap instance as parameter
response = shared_records_operations.get_shared_record_details(param_instance)
Copieddef get_share_records_details():
    import requests

    url = 'https://www.zohoapis.com/crm/v2/Contacts/3409643000002277005/actions/share'

    headers = {
        'Authorization': 'Zoho-oauthtoken 1000.04be928e4a96XXXXXXXXXXXXX68.0b9eXXXXXXXXXXXX60396e268',
    }

    parameters = {
        'view': 'summary',
        'sharedTo': '3409643000000174021'
    }

    response = requests.get(url=url, headers=headers, params=parameters)

    if response is not None:
        print("HTTP Status Code : " + str(response.status_code))

        print(response.json())

get_share_records_details()
1.0.010.x
Copied//Get instance of ShareRecordsOperations Class that takes moduleAPIName and recordId as parameter
let sharedRecordsOperations = new ShareRecordsOperations(recordId, moduleAPIName);
//Get instance of ParameterMap Class
let paramInstance = new ParameterMap();
/* Possible parameters of Get Shared Record Details operation */
await paramInstance.add(GetSharedRecordDetailsParam.VIEW, "summary");
// await paramInstance.add(GetSharedRecordDetailsParam.SHAREDTO, "3409643000000302031");
//Call getSharedRecordDetails method that takes ParameterMap instance as parameter
let response = await sharedRecordsOperations.getSharedRecordDetails(paramInstance);
Copiedasync function getShareRecordsDetails() {
    const got = require("got");

    let url = 'https://www.zohoapis.com/crm/v2/Contacts/3409643000002277005/actions/share'

    let headers = {
        Authorization : "Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
    }

    let parameters = {
        'view': 'summary',
        'sharedTo': '3409643000000174021'
    }

    let requestDetails = {
        method : "GET",
        headers : headers,
        searchParams : parameters,
        throwHttpErrors : false
    }
    
    let response = await got(url, requestDetails)
    
    if(response != null) {
        console.log(response.statusCode);
        console.log(response.body);
    }
}
getShareRecordsDetails()
2.02.x.x
Copied# Get instance of ShareRecordsOperations Class that takes module_api_name and record_id as parameter
sro = ShareRecords::ShareRecordsOperations.new(record_id, module_api_name)
# Get instance of ParameterMap Class
pm = ParameterMap.new
# Possible parameters of Get Shared Record Details operation
# Allowed values - summary, manage
pm.add(ShareRecords::ShareRecordsOperations::GetSharedRecordDetailsParam.view, 'summary')
# Call get_shared_record_details method that takes ParameterMap instance as parameter
response = sro.get_shared_record_details(pm)
Copiedclass GetSharedRecords 

    def execute
        parameters ={}
        parameters["view"]="summary"
        parameters["sharedTo"]="3477061000000173021"
        query_string = parameters.to_a.map { |x| "#{x[0]}=#{x[1]}" }.join('&')
        url= "https://www.zohoapis.com/crm/v2/Leads/3477061000005623115/actions/share"
        url += '?' + query_string if !query_string.nil? && (query_string.strip != '')
        url = URI(url)
        req = Net::HTTP::Get.new(url.request_uri)
        http = Net::HTTP.new(url.host, url.port)
        http.use_ssl = true
        headers={}
        headers["Authorization"]="Zoho-oauthtoken 1000.50XXXXXXXXX&77e3a.44XXXXXXXXX8353"
        headers&.each { |key, value| req.add_field(key, value) }
        response=http.request(req)
        status_code = response.code.to_i
        headers = response.each_header.to_h
        print status_code
        print headers
        unless response.body.nil?
            print  response.body
        end
    end
end
GetSharedRecords.new.execute
1.0.0ES6
Copied//Get instance of ShareRecordsOperations Class that takes moduleAPIName and recordId as parameter
let sharedRecordsOperations = new ZCRM.ShareRecord.Operations(recordId, moduleAPIName);
//Get instance of ParameterMap Class
let paramInstance = new ParameterMap();
/* Possible parameters of Get Shared Record Details operation */
await paramInstance.add(ZCRM.ShareRecord.Model.GetSharedRecordDetailsParam.VIEW, "summary");
// await paramInstance.add(GetSharedRecordDetailsParam.SHAREDTO, "3409643302031");
//Call getSharedRecordDetails method that takes ParameterMap instance as parameter
let response = await sharedRecordsOperations.getSharedRecordDetails(paramInstance);
Copiedvar listener = 0;
class ShareRecordsAPI {

	async shareRecords()	{
		var url = "https://www.zohoapis.com/crm/v2/Leads/34770615623115/actions/share"
        var parameters = new Map()
        var headers = new Map()
        var token = {
            clientId:"1000.NPY9M1V0XXXXXXXXXXXXXXXXXXXF7H",
            redirectUrl:"http://127.0.0.1:5500/redirect.html",
            scope:"ZohoCRM.users.ALL,ZohoCRM.bulk.read,ZohoCRM.modules.ALL,ZohoCRM.share.Leads.ALL,ZohoCRM.settings.ALL,Aaaserver.profile.Read,ZohoCRM.org.ALL,profile.userphoto.READ,ZohoFiles.files.ALL,ZohoCRM.bulk.ALL,ZohoCRM.settings.variable_groups.ALL"
        }
        var accesstoken = await new ShareRecordsAPI().getToken(token)
        headers.set("Authorization", "Zoho-oauthtoken " + accesstoken)
        parameters.set("view", "summary")
        parameters.set("sharedTo", "3477061173021")
        var requestMethod = "GET"
        var reqBody = null
        var params = "";
        parameters.forEach(function(value, key) {
            if (parameters.has(key)) {
                if (params) {
                    params = params + key + '=' + value + '&';
                }
                else {
                    params = key + '=' + value + '&';
                }
            }
        });
        var apiHeaders = {};
        if(headers) {
            headers.forEach(function(value, key) {
                apiHeaders[key] = value;
            });
        }
        if (params.length > 0){
            url = url + '?' + params.substring(0, params.length - 1);
        }
        var requestObj = {
            uri : url,
            method : requestMethod,
            headers : apiHeaders,
            body : JSON.stringify(reqBody),
            encoding: "utf8",
            allowGetBody : true,
			throwHttpErrors : false
        };
        var result = await new ShareRecordsAPI().makeAPICall(requestObj);
        console.log(result.status)
        console.log(result.response)
	}

    async getToken(token) {

        if(listener == 0) {

            window.addEventListener("storage", function(reponse) {
                if(reponse.key === "access_token" && (reponse.oldValue != reponse.newValue || reponse.oldValue == null)){
                    location.reload();
                }
                if(reponse.key === "access_token"){

                    sessionStorage.removeItem("__auth_process");
                }
            }, false);
            listener = 1;
            if(sessionStorage.getItem("__auth_process")) {
                sessionStorage.removeItem("__auth_process");
            }
        }
        ["granted_for_session", "access_token","expires_in","expires_in_sec","location","api_domain","state","__token_init","__auth_process"].forEach(function (k) {
            var isKeyExists = localStorage.hasOwnProperty(k);
            if(isKeyExists) {
                sessionStorage.setItem(k, localStorage[k]);
            }
            localStorage.removeItem(k);
        });
        var valueInStore = sessionStorage.getItem("access_token");
        var tokenInit = sessionStorage.getItem("__token_init");
        if(tokenInit != null && valueInStore != null && Date.now() >= parseInt(tokenInit) + 59 * 60 * 1000){ // check after 59th minute
            valueInStore = null;
            sessionStorage.removeItem("access_token");
        }

        var auth_process = sessionStorage.getItem("__auth_process");
        if ((valueInStore == null && auth_process == null) || (valueInStore == 'undefined' && (auth_process == null || auth_process == "true"))) {
            var accountsUrl = "https://accounts.zoho.com/oauth/v2/auth"
            var clientId;
            var scope;
            var redirectUrl;
            if(token != null) {
                clientId = token.clientId;
                scope = token.scope;
                redirectUrl = token.redirectUrl;
            }

            var fullGrant = sessionStorage.getItem("full_grant");
            var grantedForSession = sessionStorage.getItem("granted_for_session");
            if(sessionStorage.getItem("__token_init") != null && ((fullGrant != null && "true" == full_grant) || (grantedForSession != null && "true" == grantedForSession))) {
                accountsUrl += '/refresh';
            }
            if (clientId && scope) {
                sessionStorage.setItem("__token_init", Date.now());
                sessionStorage.removeItem("access_token");
                sessionStorage.setItem("__auth_process", "true");
                window.open(accountsUrl + "?" + "scope" + "=" + scope + "&"+ "client_id" +"=" + clientId + "&response_type=token&state=zohocrmclient&redirect_uri=" + redirectUrl);
                ["granted_for_session", "access_token","expires_in","expires_in_sec","location","api_domain","state","__token_init","__auth_process"].forEach(function (k) {
                    var isKeyExists = localStorage.hasOwnProperty(k);
                    if(isKeyExists){
                        sessionStorage.setItem(k, localStorage[k]);
                    }
                    localStorage.removeItem(k);
                });
                valueInStore = sessionStorage.getItem("access_token");
            }
        }
        if(token != null && valueInStore != 'undefined'){
            token.accessToken = valueInStore;
        }
        return token.accessToken;
    }

    async makeAPICall(requestDetails) {
        return new Promise(function (resolve, reject) {
            var body, xhr, i;
            body = requestDetails.body || null;
            xhr = new XMLHttpRequest();
            xhr.withCredentials = true;
            xhr.open(requestDetails.method, requestDetails.uri, true);
            for (i in requestDetails.headers) {
                xhr.setRequestHeader(i, requestDetails.headers[i]);
            }
            xhr.send(body);
            xhr.onreadystatechange = function() {
                if(xhr.readyState == 4) {
                    resolve(xhr);
                }
            }
        })
    }
}
Copiedresponse = invokeurl
[
	url: "https://www.zohoapis.com/crm/v2/Contacts/4150868000001191072/actions/share"
	type: GET
	connection:"crm_oauth_connection"
];
info response;

Parameters

  • sharedTostring, optional

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

  • viewstring, optional

    Represents the details of the shared records that you want to retrieve.
    Possible values:
    summary:Refer to the "Response Structure for 'summary' Parameter" section to know the additional keys that will be retrieved when you specify this parameter.
    manage:Refer to the "Response Structure for 'manage' Parameter" section to know the additional keys that will be retrieved when you specify this parameter.

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"

Response Structure

  • share_related_recordsboolean

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

  • permissionstring

    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.

  • userJSON 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.

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

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"

Possible Errors

  • OAUTH_SCOPE_MISMATCHHTTP 401

    invalid oauth scope to access this URLe
    Resolution: 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.

  • INVALID_URL_PATTERNHTTP 404

    Please check if the URL trying to access is a correct one
    Resolution: The request URL has syntactical errors.

  • INVALID_DATAHTTP 400

    ENTITY_ID_INVALID
    Resolution: The record ID given in the URL is either invalid
    (or)
    does not belong to the module mentioned.

  • INVALID_DATAHTTP 400

    Scheduler is running.
    Resolution: The record is either being shared or revoked currently.

  • INVALID_MODULEHTTP 400

    the module name given seems to be invalid
    Resolution: The module name specified is incorrect. Refer to supported modules section above and specify a valid module API name.

  • PATTERN_NOT_MATCHEDHTTP 400

    Please check whether the input values are correct
    Resolution: The value specified in 'view' parameter is incorrect. Refer to parameters section above and specify valid input.

  • NO_PERMISSIONHTTP 403

    Permission denied to read
    Resolution: The user does not have permission to read details of a shared record. Contact your system administrator.

  • INTERNAL_ERRORHTTP 500

    Internal Server Error
    Resolution: Unexpected and unhandled exception in Server. Contact support team.

  • INVALID_REQUEST_METHODHTTP 400

    The http request method type is not a valid one
    Resolution: You have specified an invalid HTTP method to access the API URL. Specify a valid request method. Refer to endpoints section above.

  • AUTHORIZATION_FAILEDHTTP 400

    User does not have sufficient privilege to read.
    Resolution: The user does not have the permission to read details of a shared record. Contact your system administrator.

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"
        }
    ]
}