Create Data Sharing Rule

Purpose

To create a data-sharing rule that extends access rights to CRM records for users in other roles and groups, or for all users in your Zoho CRM organization.

Note

You can use this API to create a single data sharing rule at a time.

Endpoints

POST /settings/data_sharing/rules?module={module_API_name}

Request Details

Request URL

{api-domain}/crm/{version}/settings/data_sharing/rules?module={module_API_name}

Possible module names

Leads, Contacts, Accounts, Deals, Tasks, Events, Calls, Products, Quotes, Sales_Orders, Purchase_Orders, Invoices, Campaigns, Vendors, Price_Books, Cases, Solutions

Header

Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52

Scope

ZohoCRM.settings.data_sharing.create

Supported modules

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

Parameter

modulestring, mandatory
Specify the module for which you want to create the data sharing rule, such as Leads or Contacts. You can use the GET - Modules Metadata API to retrieve the module API names.

Sample Request

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

Input JSON

name string, mandatory
Represents the name of the sharing rule.
superiors_allowed boolean, mandatory
Indicates whether the superiors of 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
type string, mandatory
Specifies the type of sharing rule. Sharing rules 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_to JSON object, mandatory
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 unique identifier of the resource.
- type string
  Specifies the type of resource to which data is shared. Possible values:
  roles- Records are shared to roles if subordinates key is false. Records are shared to roles and subordinates if subordinates key is true.
  groups- Records are shared to group
  all_users- Records are shared to all users.
- subordinatesboolean
  Indicates whether records are shared with subordinates when "type" is set to 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 JSON object, mandatory when type is Record_Owner_Based
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 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, mandatory when type is Criteria_Based
It represents the criteria for sharing records. These details should be provided when the data sharing type is criteria based.
- 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_type string, mandatory
Specifies the type of permissions or access granted. Possible values:
read- read only.
read_write- read/write.
read_write_delete- read/write/delete.

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

Note

Data sharing rules created through API automatically assigned an "active" status. Do not include the "status" key in the input JSON. Including the "status" key in the input JSON will result in an error.

Sample Input for Record Owner Based Sharing Rule

Copied{
    "sharing_rules": [
        {
            "name": "Lead sharing rule",
            "superiors_allowed": false,
            "type": "Record_Owner_Based",
            "shared_to": {
                "resource": {
                    "id": "3602353000000015966"
                },
                "type": "roles",
                "subordinates": false
            },
            "shared_from": {
                "resource": {
                    "id": "3602353000000015969"
                },
                "type": "roles",
                "subordinates": true
            },
            "permission_type": "read_write_delete"
        }
    ]
}

Sample Input for Criteria Based Sharing Rule

Copied{
    "sharing_rules": [
        {
           
            "superiors_allowed": false,
            "type": "Criteria_Based",
 "criteria": {
                "group_operator": "AND",
                "group": [
                    {
                        "comparator": "equal",
                        "field": {
                            "api_name": "City"
                        },
                        "type": "value",
                        "value": "Miami"
                    },
                    {
                        "comparator": "equal",
                        "field": {
                            "api_name": "State"
                        },
                        "type": "value",
                        "value": "Florida"
                    }
                ]
            },
            "shared_to": {
                "resource": {
                    "name": "Miami Users",
                    "id": "3602353000000601002"
                },
                "type": "groups",
                "subordinates": false
            },
            "shared_from": null,
            "permission_type": "read_write_delete",
            "name": "Lead Sharing Rule for Chennai "
        }
    ]
}

Possible Errors

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_DATA HTTP 400
The given api_name seems to be invalid
Resolution: Give correct API name for fields mentioned in criteria.
DUPLICATE_DATA HTTP 400
A sharing rule with the same name already exists.
Resolution: Try creating a sharing rule with a different name.
DEPENDENT_FIELD_MISMATCH HTTP 400
Resource type and id provided in the input JSON does not match.
Resolution: Provide a valid combination of resource type and id.
NOT_ALLOWED HTTP 400
Status key should not be passed in the Input JSON.
Resolution: Provide a valid Input JSON without status key.
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": [
        {
            "code": "SUCCESS",
            "details": {
                "id": "3602353000000608035"
            },
            "message": "sharing rule is created successfully",
            "status": "success"
        }
    ]
}