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 POSTInput JSON
- name string, mandatoryRepresents the name of the sharing rule.
- superiors_allowed boolean, mandatoryIndicates 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, mandatorySpecifies 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 stringSpecifies 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. - subordinatesbooleanIndicates 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 stringRepresents 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 booleanIndicates 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, mandatorySpecifies the type of permissions or access granted. Possible values:
read- read only.
read_write- read/write.
read_write_delete- read/write/delete.
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"
}
]
}