Data Sharing APIs

Data Sharing in Zoho CRM gives you an option to extend the access rights to CRM records for users belonging to other roles and groups. By default, the Organization Permissions is set as private allowing only the record owner and their manager can view and access the CRM data.

Users with Module Customization permission in their profile can access this feature. For users with administrative profile this permission will be enabled by default. To enable Modules Customization permission, go to Setup > Security Control > Profiles. Select the desired profile that require the permission, and enable Module Customization option in Admin Level section under Setup Permission.

Get Data Sharing Rules

Purpose

To retrieve the list of data sharing rules configured in your Zoho CRM organization.

Endpoints

GET /settings/data_sharing/rules
GET /settings/data_sharing/rules/{rule_ID}

Request Details

Request URL

To retrieve all data sharing rules:
{api-domain}/crm/{version}/settings/data_sharing/rules

To get a specific sharing rule:
{api-domain}/crm/{version}/settings/data_sharing/rules/{rule_ID}

Supported modules

Leads, Accounts, Contacts, Deals, Tasks, Meetings, Calls, Products, Vendors, Price Books, Quotes, Sales Orders, Purchase Orders, Invoices, and Custom modules

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.data_sharing.READ

Parameters

modulestring, optional
Specify the API name of the module for which you want to fetch data sharing rules. For example, Leads, Contacts, Accounts, Deals, and so on.

Sample Request to retrieve all data sharing rules

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/data_sharing/rules"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X GET

Response JSON

moduleJSON object
Represents the module to which the sharing rule applies. It consists of the API name and the display label, and the unique identifier of the module.
superiors_allowedboolean
Indicates whether the superiors to the particular role or group with whom the records are shared are allowed access to the records or not.
Possible values:
true- Superiors are allowed access
false- Superiors are not allowed access
typestring
Specifies the type of sharing rule, which can be based on the record owner or on specific criteria for the records to be shared.
Possible values:
Record_Owner_Based- Data sharing is based on the record owner
Criteria_Based- Data sharing is based on the criteria.
shared_toJSON object
Represents the details of the resource to which data is shared. Data can be shared to roles, roles and subordinates, groups, or all users.
- resourceJSON object
  Represents the resource to which data is shared. It consists of the name and unique identifier of the resource.
- type string
  Specifies the type of the resource to which data is shared. Possible values:
  roles- Record is shared to roles if subordinates key is false. Record is shared to roles and subordinates if subordinates key is true.
  Possible values:
  groups- Record is shared to group
  all_users- Records is shared to all users.
- subordinatesboolean
  Indicates whether subordinates are included when "type" key is roles.
  Possible values:
  true- Subordinates are included.
  false- Subordinates are not included.
The keys "type" and "subordinates" together denote these possibilities of data sharing (roles, roles and subordinates, all users or groups) as below.
Resource to which data is shared Type Subordinates
Groups groups false
Roles roles false
Roles and subordinates roles true
All users all_users false
shared_from
Represents the details of the resource whose data is shared. These details are available when the data sharing type is record owner based. Data can be shared from roles, roles and subordinates, or groups.
- resourceJSON object
  Represents the resource whose data is shared. It consists of the name and unique identifier of the resource.
- type string
  Represents the type of the resource whose data is shared. Data can be shared from roles, roles and subordinates, or groups. Possible values:
  roles- Record is shared from roles if subordinates key is false. Record is shared from roles and subordinates if subordinates key is true.
  groups- Record is shared to group.
- subordinates boolean
  Indicates whether subordinates are included when "type" key is roles.
  Possible values:
  true- Subordinates are included.
  false- Subordinates are not included.
The keys "type" and "subordinate"s together represent the different types of resources whose data can be shared (e.g., roles, roles and subordinates, or groups), as explained below.
Resource to which data is shared Type Subordinates
Groups groups false
Roles roles false
Roles and subordinates roles true
criteria JSON object
It represents the criteria for sharing records. These details are available when the data sharing type is criteria based and a specific data sharing rule is fetched. Refer to the sample response when a specific rule is retreived here.
- group_operator string
  Specifies the group operator used in the criteria
- group JSON array
  It represents the group of criteria for filtering records.
  - fieldJSON object
    It represents the API name of the field.
  - comparatorstring
    It represents the comparison operator used in the criterion.
  - valuestring
    It represents the value used in the criterion.
permission_typestring
Specifies the type of permissions or access granted.
Possible values:
read- read only
read_write- read/write.
read_write_delete- read/write/delete.
namestring
Represents the name of the sharing rule.
idstring
Represents the unique identifier for this sharing rule.
match_limit_exceeded boolean
Indicates whether the rule matched more than the maximum limit of four million records.
Possible values:
true
false

Resource to which data is shared	Type	Subordinates
Groups	groups	false
Roles	roles	false
Roles and subordinates	roles	true
All users	all_users	false

Resource to which data is shared	Type	Subordinates
Groups	groups	false
Roles	roles	false
Roles and subordinates	roles	true

Sample Response when all data sharing rules are retrieved

Copied{
    "sharing_rules": [
        {
            "module": {
                "api_name": "Leads",
                "name": "Leads",
                "id": "3602353000000000125"
            },
            "superiors_allowed": true,
            "type": "Record_Owner_Based",
            "shared_to": {
                "resource": {
                    "name": "Manager",
                    "id": "3602353000000015969"
                },
                "type": "roles",
                "subordinates": false
            },
            "shared_from": {
                "resource": {
                    "name": "CEO",
                    "id": "3602353000000015966"
                },
                "type": "roles",
                "subordinates": false
            },
            "permission_type": "read_write",
            "name": "Rule1",
            "id": "3602353000000603003",
            "status": "active",
            "match_limit_exceeded": false
        },
        {
            "module": {
                "api_name": "Accounts",
                "name": "Accounts",
                "id": "3602353000000000127"
            },
            "superiors_allowed": false,
            "type": "Record_Owner_Based",
            "shared_to": {
                "resource": {
                    "name": "User Group1",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": {
                "resource": {
                    "name": "CEO",
                    "id": "3602353000000015966"
                },
                "type": "roles",
                "subordinates": false
            },
            "permission_type": "read_write_delete",
            "name": "Accounts sharing rules",
            "id": "3602353000000602055",
            "status": "active",
            "match_limit_exceeded": false
        },
        {
            "module": {
                "api_name": "Accounts",
                "name": "Accounts",
                "id": "3602353000000000129"
            },
            "superiors_allowed": false,
            "type": "Criteria_Based",
            "shared_to": {
                "resource": {
                    "name": "User Group NY",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": null,
            "permission_type": "read_write_delete",
            "name": "NY Rule",
            "id": "3602353000000602043",
            "status": "active",
            "match_limit_exceeded": false
        }
    ],
    "info": {
        "per_page": 200,
        "count": 3,
        "page": 1,
        "more_records": false
    }
}

Sample Request to get a specific rule

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/data_sharing/rules/3602353000000602043"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-X GET

Possible Errors

NO CONTENTHTTP 204
When sharing rules are not configured.
INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP GET method to make this API call. Any other request method will result in this error.
OAUTH_SCOPE_MISMATCHHTTP 401
The access token you have used to make this API call does not have the required scope.
Resolution: Generate a new access token with the required scopes for this API. Refer to Scope section at the beginning of this page for the list of required scopes.
NO_PERMISSIONHTTP 403
You do not have Modules Customization permission.
Resolution: Get permission for the Modules Customization.
INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to request URL section at the beginning of this page for more details.
INTERNAL_ERRORHTTP 500
Unexpected and unhandled exception in the server.
Resolution: Contact the support team at support@zohocrm.com.

Sample Response when a specific rule (Criteria based rule) is retreived

Copied{
    "sharing_rules": [
        {
              "criteria": {
                "comparator": "equal",
                "field": {
                    "api_name": "Billing_City",
                    "id": "3643104000000002467"
                },
                "type": "value",
                "value": "New York"
            },
            "module": {
                "api_name": "Accounts",
                "name": "Accounts",
                "id": "3602353000000000129"
            },
            "superiors_allowed": false,
            "type": "Criteria_Based",
            "shared_to": {
                "resource": {
                    "name": "User Group NY",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": null,
            "permission_type": "read_write_delete",
            "name": "NY Rule",
            "id": "3602353000000602043",
            "status": "active",
            "match_limit_exceeded": false
        }
    ]
}