Search Data Sharing Rules API

Purpose

To retrieve data sharing rules from your CRM that meet specific criteria, filtering by attributes such as status, shared-to roles or groups, permission type, and other key details.

POST /settings/data_sharing/rules/search

Request Details

Request URL

{api-domain}/crm/{version}/settings/data_sharing/rules/search

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.data_sharing.READ

Supported modules

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

Sample Request

Copiedcurl "https://www.zohoapis.com/crm/v8/settings/data_sharing/rules/search"
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d @searchdatasharingrules.json
-X POST

Input JSON

group_operator string, mandatory when specifying multiple criteria within the group key of your request
Specifies how the filter conditions are combined.
Possible values:
and- This operator combines different groups of filter conditions such that all conditions must be met for a record to be included in the results.
or- This operator combines groups of filter conditions such that only one of the conditions needs to be met for a record to be included.
group array, optional
Contains individual filter conditions.
- field JSON object, mandatory
  Represents the field being filtered.
  - api_name string, mandatory
    Represents the API name of the field.
- value string or array, mandatory
  The value to compare against.
- comparator string, mandatory
  The comparison operator.
  Possible values:equal, in, like.

The table below presents a list of keys and their corresponding operators:

Key	Operator
superiors_allowed	equal
status	equal
shared_to.type	equal
shared_to.resource.id	in
shared_from.type	equal
shared_to.resource.id	in
name	like
permission_type	equal

Sample Filter

Copied{
    "filters": [
        {
            "group_operator": "and",
            "group": [
                {
                    "group_operator": "or",
                    "group": [
                        {
                            "group_operator": "and",
                            "group": [
                                {
                                    "field": {
                                        "api_name": "shared_to.resource.id"
                                    },
                                    "value": [
                                        "3602353000000601002"
                                    ],
                                    "comparator": "in"
                                },
                                {
                                    "field": {
                                        "api_name": "shared_to.type"
                                    },
                                    "value": "groups",
                                    "comparator": "equal"
                                }
                            ]
                        },
                        {
                            "group_operator": "and",
                            "group": [
                                {
                                    "field": {
                                        "api_name": "shared_to.resource.id"
                                    },
                                    "value": [
                                        "3602353000000015969"
                                    ],
                                    "comparator": "in"
                                },
                                {
                                    "field": {
                                        "api_name": "shared_to.type"
                                    },
                                    "value": "roles",
                                    "comparator": "equal"
                                }
                            ]
                        }
                    ]
                },
                {
                    "field": {
                        "api_name": "status"
                    },
                    "value": "active",
                    "comparator": "equal"
                }
            ]
        }
    ]
}

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

Possible Errors

NO CONTENTHTTP 204
When sharing rules are not present.
INVALID_DATA HTTP 400
- Maximum length exceeded for the number of sharing rules.
  Resolution: You can create only one sharing rule at a time. Try creating a single sharing rule.
- Invalid criteria given
  Resolution: Specify valid criteria. Refer to the Input JSON section for more details.
- Invalid data given in the filters JSON array
  Resolution: Specify valid values in the "filters" JSON array. Refer to the above Input JSON and table sections for more details.
- Invalid data given in the field JSON object
  Resolution: Specify valid values in the "field" JSON object. Refer to the Input JSON section for more details.
- Invalid comparator given
  Resolution: Specify valid comparators in the input body. Refer to the Input JSON section for more details.
- Invalid value given in the "group_operator" key
  Resolution: Specify a valid value. Supported values are "AND", "OR".
MANDATORY_NOT_FOUNDHTTP 400
One or more mandatory keys missing
Resolution: Specify all the mandatory keys. Refer to the Input JSON section to know the mandatory fields.
DEPENDENT_FIELD_MISSINGHTTP 400
One or more dependent fields are missing
Resolution: Check the Input JSON section to avoid missing dependent fields.
EXPECTED_FIELD_MISSINGHTTP 400
The "filters" JSON array is empty
Resolution: Specify atleast one filter in the "filters" JSON array.
NOT_ALLOWED HTTP 400
Status key should not be passed in the Input JSON.
Resolution: Provide a valid Input JSON without status key.
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

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_delete",
            "name": "Lead Sharing Rules",
            "id": "3602353000000603003",
            "status": "active",
            "match_limit_exceeded": false
        },
        {
            "module": {
                "api_name": "Leads",
                "name": "Leads",
                "id": "3602353000000000125"
            },
            "superiors_allowed": false,
            "type": "Criteria_Based",
            "shared_to": {
                "resource": {
                    "name": "User Group1",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": null,
            "permission_type": "read_write_delete",
            "name": "Deal Sharing Rule 1",
            "id": "3602353000000608013",
            "status": "active",
            "match_limit_exceeded": false
        },
        {
            "module": {
                "api_name": "Leads",
                "name": "Leads",
                "id": "3602353000000000125"
            },
            "superiors_allowed": false,
            "type": "Criteria_Based",
            "shared_to": {
                "resource": {
                    "name": "User Group1",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": null,
            "permission_type": "read_write_delete",
            "name": "Lead Sharing Rule for Chennai",
            "id": "3602353000000608023",
            "status": "active",
            "match_limit_exceeded": false
        },
        {
            "module": {
                "api_name": "Leads",
                "name": "Leads",
                "id": "3602353000000000125"
            },
            "superiors_allowed": false,
            "type": "Criteria_Based",
            "shared_to": {
                "resource": {
                    "name": "User Group1",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": null,
            "permission_type": "read_write_delete",
            "name": "Lead Sharing Rule for Chennai 2",
            "id": "3602353000000608035",
            "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": "User Group1",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "permission_type": "read_write_delete",
            "name": "Accounts sharing rules",
            "id": "3602353000000602055",
            "status": "active",
            "match_limit_exceeded": false
        },
        {
            "module": {
                "api_name": "Deals",
                "name": "Deals",
                "id": "3602353000000000131"
            },
            "superiors_allowed": false,
            "type": "Criteria_Based",
            "shared_to": {
                "resource": {
                    "name": "User Group1",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": null,
            "permission_type": "read_write_delete",
            "name": "Deal Sharing Rule",
            "id": "3602353000000609009",
            "status": "active",
            "match_limit_exceeded": false
        }
    ],
    "info": {
        "per_page": 200,
        "count": 6,
        "page": 1,
        "more_records": false
    }
}