Zoho: Share a record

← Share records operations · Get started

Operation zoho.createsharerecords

Provider route: POST /crm/v8/{moduleApiName}/{recordId}/actions/share. Alter supplies the connection’s credentials and routing.

Call through Alter

Install @alter-ai/sdk @alter-ai/zoho with npm, or alter-sdk-zoho with pip. Supply your connected customer’s grant ID and the arguments described below.

import { App } from "@alter-ai/sdk";
import { ZohoIntegration } from "@alter-ai/zoho";

async function execute(input: Parameters<ZohoIntegration["shareRecords"]["createShareRecords"]>[0]) {
  const app = new App({ apiKey: process.env.ALTER_API_KEY! });
  try {
    const provider = new ZohoIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! });
    const call = await provider.shareRecords.createShareRecords(input);
    const result = await call.wait();
    return result.bodyJson();
  } finally {
    await app.close();
  }
}

import os
from alter_sdk import App
from alter_sdk_zoho import ZohoIntegration

async def execute(arguments):
    async with App(api_key=os.environ["ALTER_API_KEY"]) as app:
        provider = ZohoIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]})
        call = await provider.share_records.create_share_records(arguments)
        result = await call.wait()
        return result.body_json()

Input

Field	Type	Presence	Description and constraints
$	object	Root	Additional keys: not allowed
path	object	Required within parent	Additional keys: not allowed
path.moduleApiName	string	Required within parent	Unique API identifier for the module used in third-party integrations; starts with a letter, contains only alphanumeric characters and underscores, and has no consecutive or trailing underscores. Maximum length: 50
path.recordId	string	Required within parent	Represents the unique identifier of the RecordGETDataItem record. Format: int64
body	object	Required within parent	Represents the request body. Additional keys: not allowed
body.notify_on_completion	boolean	Optional	Specify whether to send an email notification to the record owner once the share action is completed. Possible values: - true - false
body.notify_shared_members	boolean	Optional	Specify whether to send a notification to the members with whom the record is shared. Possible values: - true - false
body.share	array	Required within parent	Specify the list of share entries to apply. Each entry defines a recipient, the access level, and the type of sharing. You can provide a maximum of 20 entries in a single request. Maximum items: 20
body.share[]	object	Each item	Each object represents an entry in the array. Additional keys: not allowed
body.share[].permission	string	Required within parent	Specify the level of access to grant for the shared record. Possible values: - read_only - read_write - full_access One of: read_only, read_write, full_access
body.share[].share_related_records	boolean	Optional	Specify whether to share the related records along with the record. Possible values: - true - false
body.share[].shared_with	JSON	Required within parent	Specify the details of the entity (user, role, or group) with which to share the record.
body.share[].shared_with (anyOf 1)	object	Alternative	Indicates that you can share the record along with roles. Additional keys: not allowed
body.share[].shared_with (anyOf 1).id	string	Required within parent	Represents the ID of the role with whom the record is being shared. Maximum length: 19
body.share[].shared_with (anyOf 1).type	string	Required within parent	type of entity with whom the record is shared One of: roles
body.share[].shared_with (anyOf 2)	object	Alternative	Indicates that you can share the record along with groups. Additional keys: not allowed
body.share[].shared_with (anyOf 2).id	string	Required within parent	Represents the ID of the group with whom the record is being shared. Maximum length: 19
body.share[].shared_with (anyOf 2).type	string	Required within parent	type of entity with whom the record is shared One of: groups
body.share[].shared_with (anyOf 3)	object	Alternative	Indicates that you can share the record along with users. Additional keys: not allowed
body.share[].shared_with (anyOf 3).id	string	Required within parent	Represents the ID of the user with whom the record is being shared. Maximum length: 19
body.share[].shared_with (anyOf 3).type	string	Required within parent	type of entity with whom the record is shared One of: users
body.share[].type	string	Required within parent	Specify the type of sharing to apply to the record. Possible values: - private - public One of: private, public

Response

Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.

Field	Type	Presence	Description and constraints
$	JSON	Root
$ (anyOf 1)	object	Alternative	Represents the success response of the API request. Additional keys: not allowed
$ (anyOf 1).share	array	Required within parent	Represents details of each share record creation result. Maximum items: 20
$ (anyOf 1).share[]	Model	Each item	Expand Update share permissions — response body — share share item
$ (anyOf 2)	object	Alternative	Represents the response of partial success. Additional keys: not allowed
$ (anyOf 2).share	array	Optional	Represents the details of each share record creation result. Maximum items: 20
$ (anyOf 2).share[]	object	Each item	Represents the per-entry result for one share entry, which can be either a success result or a specific error. Additional keys: allowed
$ (anyOf 2).share[] (anyOf 1)	Model	Alternative	Expand Update share permissions — response body — share share item
$ (anyOf 2).share[] (anyOf 2)	JSON	Alternative	Each string represents the per-entry result for one share entry, which can be either a success or a specific error.
$ (anyOf 2).share[] (anyOf 2) (anyOf 1)	Model	Alternative	Expand Update share permissions — response body — Represents the partial success response / share / item / value / code: MANDATORY NOT FOUND, message: required field not found, status: error
$ (anyOf 2).share[] (anyOf 2) (anyOf 2)	Model	Alternative	Expand Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error — Invalid Type Error Response
$ (anyOf 2).share[] (anyOf 2) (anyOf 3)	Model	Alternative	Expand Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error — Invalid Share With Value Error Response
$ (anyOf 2).share[] (anyOf 2) (anyOf 4)	Model	Alternative	Expand Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, status: error
$ (anyOf 2).share[] (anyOf 2) (anyOf 5)	Model	Alternative	Expand Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: cannot share the related records, status: error
$ (anyOf 2).share[] (anyOf 2) (anyOf 6)	Model	Alternative	Expand Update share permissions — response body — Represents the partial success response / share / item / value / code: LIMIT EXCEEDED, status: error

Referenced models: Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: cannot share the related records, status: error, Update share permissions — response body — share share item, Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, status: error, Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error — Invalid Share With Value Error Response, Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error — Invalid Type Error Response, Update share permissions — response body — Represents the partial success response / share / item / value / code: LIMIT EXCEEDED, status: error, Update share permissions — response body — Represents the partial success response / share / item / value / code: MANDATORY NOT FOUND, message: required field not found, status: error

Schemas

Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: cannot share the related records, status: error

Field	Type	Presence	Description and constraints
$	object	Root	Represents the error response returned when **share_related_records** is set on a module that does not support sharing related records. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned by the API. Known values: INVALID_DATA
details	object	Required within parent	Represents the additional information about the response. Additional keys: not allowed
details.api_name	string	Required within parent	Represents the API name of the parameter that caused the error. Maximum length: 50
details.json_path	string	Required within parent	Represents the JSON path of the parameter that caused the error. Maximum length: 100
message	string	Required within parent	Represents the response message returned by the API. Known values: cannot share the related records
status	string	Required within parent	Represents the status of the API call. Known values: error

Update share permissions — response body — share share item

Field	Type	Presence	Description and constraints
$	object	Root	Represents the per-entry success result of a share record create or update operation. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned by the API. Known values: SUCCESS
details	object	Required within parent	Represents the additional information about the response. Additional keys: not allowed
message	string	Required within parent	Represents the response message returned by the API. Known values: record will be shared successfully
status	string	Required within parent	Represents the status of the API call. Known values: success

Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, status: error

Field	Type	Presence	Description and constraints
$	object	Root	Represents the error response returned when the recipient ID in **shared_with** is invalid or when the record cannot be shared with the specified entity. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned by the API. Known values: INVALID_DATA
details	object	Required within parent	Represents the additional information about the response. Additional keys: not allowed
details.api_name	string	Required within parent	Represents the API name of the parameter that caused the error. Maximum length: 50
details.json_path	string	Required within parent	Represents the JSON path of the parameter that caused the error. Maximum length: 100
message	string	Required within parent	Represents the response message returned by the API. **Possible values**: - invalid data - invalid user Id - invalid role Id - invalid group Id - cannot share to the user Known values: invalid data, invalid user Id, invalid role Id, invalid group Id, cannot share to the user
status	string	Required within parent	Represents the status of the API call. Known values: error

Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error — Invalid Share With Value Error Response

Field	Type	Presence	Description and constraints
$	object	Root	Represents the error response returned when the **shared_with** object in a share entry is invalid due to a dependent field mismatch. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned by the API. Known values: INVALID_DATA
details	Model	Required within parent	Expand Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error details
message	string	Required within parent	Represents the response message returned by the API. Known values: invalid data
status	string	Required within parent	Represents the status of the API call. Known values: error

Referenced models: Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error details

Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error — Invalid Type Error Response

Field	Type	Presence	Description and constraints
$	object	Root	Represents the error response returned when the `type` or `permission` field in a share entry does not match the expected pattern. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned by the API. Known values: INVALID_DATA
details	object	Required within parent	Represents the additional information about the response. Additional keys: not allowed
details.api_name	string	Required within parent	Represents the API name of the parameter that caused the error. **Possible values**: - type - permission Known values: type, permission
details.json_path	string	Required within parent	Represents the JSON path of the parameter that caused the error. Maximum length: 100
details.regex	string	Required within parent	Represents the regular expression pattern expected for the parameter value. Known values: private|public, read_only|read_write|full_access
message	string	Required within parent	Represents the response message returned by the API. Known values: invalid data
status	string	Required within parent	Represents the status of the API call. Known values: error

Update share permissions — response body — Represents the partial success response / share / item / value / code: LIMIT EXCEEDED, status: error

Field	Type	Presence	Description and constraints
$	object	Root	Represents the error response returned when the share entry exceeds the per-record sharing limit for the recipient type. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned by the API. Known values: LIMIT_EXCEEDED
details	object	Required within parent	Represents the additional information about the response. Additional keys: not allowed
details.api_name	string	Optional	Represents the API name of the parameter that caused the error. Known values: type
details.json_path	string	Optional	Represents the JSON path of the parameter that caused the error. Maximum length: 100
details.limit	JSON	Optional
details.limit (anyOf 1)	integer	Alternative	Represents the maximum number of share records allowed for the entity type. Format: int32
details.limit (anyOf 2)	string	Alternative	Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$
message	string	Required within parent	Represents the response message returned by the API. Maximum length: 100
status	string	Required within parent	Represents the status of the API call. Known values: error

Update share permissions — response body — Represents the partial success response / share / item / value / code: MANDATORY NOT FOUND, message: required field not found, status: error

Field	Type	Presence	Description and constraints
$	object	Root	Represents the error response returned when a mandatory field is missing from the share entry. Additional keys: not allowed
code	string	Required within parent	Represents the response code returned by the API. Known values: MANDATORY_NOT_FOUND
details	object	Required within parent	Represents the additional information about the response. Additional keys: not allowed
details.api_name	string	Required within parent	Represents the API name of the parameter that caused the error. Maximum length: 50
details.json_path	string	Required within parent	Represents the JSON path of the parameter that caused the error. Maximum length: 100
message	string	Required within parent	Represents the response message returned by the API. Known values: required field not found
status	string	Required within parent	Represents the status of the API call. Known values: error

Update share permissions — response body — Represents the partial success response / share / item / value / code: INVALID DATA, message: invalid data, status: error details

Field	Type	Presence	Description and constraints
$	object	Root	Represents the additional information about the response. Additional keys: not allowed
api_name	string	Required within parent	Represents the API name of the parameter that caused the error. Maximum length: 50
dependee	object	Required within parent	Represents the details of the parameter on which this parameter depends. Additional keys: not allowed
dependee.api_name	string	Required within parent	Represents the API name of the parameter that caused the error. Maximum length: 50
dependee.json_path	string	Required within parent	Represents the JSON path of the parameter that caused the error. Maximum length: 100
json_path	string	Required within parent	Represents the JSON path of the parameter that caused the error. Maximum length: 100

Policy, approvals and errors

SDK function policy ID: zoho.createsharerecords. Catalog operation: createShareRecords. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.

Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.

Official provider source