Share Records
Purpose
To share a record with other users, groups, and roles in the organization in Zoho CRM.
Endpoints
- POST /{module_API_name}/{record_ID}/actions/share
Request Details
Request URL
{api-domain}/crm/{version}/{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 modules.
Header
Authorization: Zoho-oauthtoken d92d4xxxxxxxxxxxxx15f52
Scope
ZohoCRM.share.{module_name}.{operation_type}
(or)
ZohoCRM.share.all
Possible module names
Leads, Accounts, Contacts, Deals, Campaigns, Cases, Solutions, Products, Vendors, Price_Books, Quotes, Sales_Orders, Purchase_Orders, Invoices, and custom.
Possible operation types
ALL - Full access to the record
CREATE - Share records with other users in the organization
Note
- The records can be shared to other users in the organization only if certain conditions are met. For simplicity, let us assume that User A shares a record with User B. Now, user A can share the record successfully only if:
- User B is a confirmed and active user.
- User B does not already have access to that particular record.
- User B has access to that particular module. For instance, to share a contact, user B must have access to the Contacts module.
- You cannot share the records in Calls, Meetings, Tasks, and Linking modules directly. They can be shared as related lists.
- The users who have profiles with share permission can share any records that they have access to, except the records that are shared to them. To check the same, go to Setup> Users and Control> Security Control> Choose the profile> Tool Permissions. Check if 'share' is enabled. It is enabled by default for Standard and Administrator Profiles.
- The details of the records that form many to many relationships (with multi-select lookup) cannot be shared.
- A record can be shared only with 10 users, 5 groups, and 5 roles.
- Once the record gets shared successfully, the user who initiated the share operation can be notified via email.
- The user can update the shared records using the PUT method. To know more, refer to Update Records.
Sample Request
Copiedcurl "https://www.zohoapis.com/crm/v8/Leads/3652397000001970045/actions/share"
-X POST
-H "Authorization: Zoho-oauthtoken 1000.8cb99dxxxxxxxxxxxxx9be93.9b8xxxxxxxxxxxxxxxf"
-d "@input.json"In the request, "@input.json" contains the sample input data.
Input JSON
- shareJSON array, mandatory
Each JSON object represents the set of users, roles, or groups with whom you want to share the record.
share Properties
- shared_withJSON object, mandatory
- type string, mandatory
Represents whether you want to share the record with users, groups, or roles.
Possible values :users, groupsroles. - id string, mandatory
The ID of the user, group, or role you want to share the record with.
- type string, mandatory
- share_related_records Boolean, optional
Represents if you want to share the related records also with the user.
Possible values:
false - Do not share related records. This is the default value.
true - Share related records along with the record. - permissionstring, mandatory
Represents the access permission you want to give the user for the shared record.
Possible values:
full_access- Allow the user full access to the record. This is the default value.
read_only - Allow the user to only view the record.
read_write - Allow the user to view and edit the record. - typestring, mandatory
Represents if the record is shared publicly (to all the users in the org) or privately (to a specific user in the org).
Possible values:
public - share to all the users in the org.
private - share to the specific user.
Note that when sharing a record privately ("type" : "private"), the share_with JSON object key is mandatory. - notify_shared_members Boolean, optional
Specifies whether to send notifications to all members with whom the record is shared.
Possible values:
false - Does not notify the user. This is the default value.
true - Notifies the user. - notify_on_completion Boolean, optional
Indicates if an email notification should be sent to the owner once the record share action is completed..
Possible values:
true - Notifies the owner. This is the default value.
false - Does not notify the owner.
Sample Input
Copied{
"share": [
{
"shared_with": {
"id": "5725767000002350003",
"type": "roles"
},
"share_related_records": false,
"permission": "full_access",
"type": "private"
},
{
"shared_with": {
"id": "5725767000002868044",
"type": "groups"
},
"share_related_records": false,
"permission": "full_access",
"type": "private"
},
{
"shared_with": {
"id": "5725767000002868058",
"type": "roles"
},
"share_related_records": false,
"permission": "full_access",
"type": "private"
},
{
"shared_with": {
"id": "5725767000002868072",
"type": "users"
},
"share_related_records": false,
"permission": "full_access",
"type": "private"
},
{
"shared_with": {
"id": "5725767000002868086",
"type": "groups"
},
"share_related_records": false,
"permission": "full_access",
"type": "private"
}
],
"notify_shared_members": false,
"notify_on_completion": true
}Possible Errors
- INVALID_DATAHTTP 400
- You have specified an invalid entity ID.
Resolution: The record ID given in the URL is either invalid
(or)
does not belong to the specified module. Specify a valid record ID. - Either the value for "permission" or the "type" key is incorrect.
Resolution: Specify a valid value. Refer to the Input JSON section for more details. - Record is already visible to the user.
Resolution: The record is already accessible by the user. You can share the record only if the user cannot access it. - Cannot share to the user
Resolution: Specify another user to share the record with. Refer to the Note section for conditions on which a record can be shared with a user.
- You have specified an invalid entity ID.
- INVALID_REQUEST_METHODHTTP 400
The request method is incorrect.
Resolution: Use the HTTP POST method to make this API call. Any other request method will result in this error. - AUTHORIZATION_FAILEDHTTP 400
User does not have sufficient privilege to share records.
Resolution: Contact your system administrator. - INVALID_MODULEHTTP 400
The module name given seems to be invalid or you have specified an unsupported module..
Resolution: Specify a valid module API name. Refer to the Supported Modules list for more details. - AMBIGUITY_DURING_PROCESSINGHTTP 400
For public sharing, more than one json object is given.
Resolution: When you share a record and make it public, you must include only one JSON object in the input with the keys "type", "permission", and "share_related_records". You cannot make a record publicly available and share it to specific users. - CANNOT_PROCESSHTTP 400
Scheduler is running.
Resolution: The record in the request has already been scheduled for sharing. Please try again later. - MANDATORY_NOT_FOUNDHTTP 400
Mandatory fields missing.
Resolution: One or more mandatory fields are missing. Specify all the mandatory fields in the input. Refer to the Input JSON section for more details. - 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 the Scope section at the beginning of this page for the list of required scopes. - LIMIT_EXCEEDEDHTTP 403
The record sharing limit has been reached.
Resolution: Please share the record within the specified limits. You can share a record with up to 10 users, 5 groups, and 5 roles. - NOT_ALLOWEDHTTP 403
Feeds is not enabled for this org.
Resolution: You cannot notify the users when you have removed "Feeds" from "Organize Modules". Add "Feeds" to "Organize Modules" to notify users when you share a record. - NO_PERMISSIONHTTP 403
Permission denied to share records.
Resolution: Contact your system administrator. - INVALID_URL_PATTERNHTTP 404
The request URL is incorrect.
Resolution: Specify a valid request URL. Refer to the 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{
"share": [
{
"code": "SUCCESS",
"details": {},
"message": "record will be shared successfully",
"status": "success"
},
{
"code": "SUCCESS",
"details": {},
"message": "record will be shared successfully",
"status": "success"
},
{
"code": "SUCCESS",
"details": {},
"message": "record will be shared successfully",
"status": "success"
},
{
"code": "SUCCESS",
"details": {},
"message": "record will be shared successfully",
"status": "success"
},
{
"code": "SUCCESS",
"details": {},
"message": "record will be shared successfully",
"status": "success"
}
]
}